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About This Book 


This book describes the Open Object Rexx Interpreter, called the interpreter or language processor in 
the following, and the object-oriented Rexx language. 


This book is intended for people who plan to develop applications using Rexx. Its users range from the 
novice, who might have experience in some programming language but no Rexx experience, to the 
experienced application developer, who might have had some experience with Object Rexx. 


This book is a reference rather than a tutorial. It assumes you are already familiar with object-oriented 
programming concepts. 


Descriptions include the use and syntax of the language and explain how the language processor 
"interprets" the language as a program is running. 


1. Related Information 


See also: Open Object Rexx: Programming Guide 


2. How to Read the Syntax Diagrams 


Throughout this book, syntax is described using the structure defined below. 


* Read the syntax diagrams from left to right, from top to bottom, following the path of the line. 
The >>--- symbol indicates the beginning of a statement. 
The ---> symbol indicates that the statement syntax is continued on the next line. 
The »--- symbol indicates that a statement is continued from the previous line. 
The --->< symbol indicates the end of a statement. 


Diagrams of syntactical units other than complete statements start with the >--- symbol and end with 
the ---> symbol. 


* Required items appear on the horizontal line (the main path). 


2»»-STATEMENT--required item------------------------------------ >< 


* Optional items appear below the main path. 
>>-5ТАТЕМЕКТ--%--------------- %-------------------------------- >< 
+-optional_item-+ 
* If you can choose from two or more items, they appear vertically, in a stack. If you must choose one of 


the items, one item of the stack appears on the main path. 


PPSZSIATEMENT--t-required.choicei-4--------------—-——--ocoooeL on >< 
+-required_choice2-+ 


* If choosing one of the items is optional, the entire stack appears below the main path. 


»»-STATEMENT--4------------------ xam mccum C E >< 
+-optional_choice1-+ 
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+-optional_choice2-+ 


* If one of the items is the default, it appears above the main path and the remaining choices are shown 
below. 


+-default_choice--+ 
>>-STATEMENT--+----------------- %------------------------------ >< 

+-optional_choice-+ 

+-optional_choice-+ 


* An arrow returning to the left above the main line indicates an item that can be repeated. 


2»»-STATEMENT----repeatable item-*------------------------------ >< 
A repeat arrow above a stack indicates that you can repeat the items in the stack. 


* A set of vertical bars around an item indicates that the item is a fragment, a part of the syntax diagram 
that appears in greater detail below the main diagram. 


>>-STATEMENT--| fragment |------------------------------------- >< 
fragment: 
| -- expansion, provides, greater detail---------------------------- | 


* Language keywords appear in uppercase (for example, SAY). They must be spelled exactly as shown 
but you can type them in upper, lower, or mixed case. Variables appear in all lowercase letters (for 
example, parmx). They represent user-supplied names or values. 


* Class and method names appear in mixed case (for example, .0bject^new). They must be spelled 
exactly as shown but you can type them in upper, lower, or mixed case. 


* If punctuation marks, parentheses, arithmetic operators, or such symbols are shown, you must enter 
them as part of the syntax. 


The following example shows how the syntax is described: 


V | 
»»-MAX(----number-4--)----------------------------------------- >< 


3. Getting Help 


The Open Object Rexx Project has a number of methods to obtain help for ooRexx. These methods, in 
no particular order of preference, are listed below. 


3.1. The Rexx Language Association Mailing List 


The Rexx Language Association (http://www.rexxla.org/) maintains a mailing list for its members. This 
mailing list is only available to RexxLA members thus you will need to join RexxLA in order to get on 
the list. The dues for RexxLA membership are small and are charged on a yearly basis. For details on 
joining RexxLA please refer to the RexxLA Home Page (http://rexxla.org/) or the RexxLA Membership 
Application (http://www.rexxla.org/rexxla/join.html) page. 
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3.2. The Open Object Rexx SourceForge Site 


The Open Object Rexx Project (http://www.oorexx.org/) utilizes SourceForge (http://sourceforge.net/) to 
house the ooRexx Project (http://sourceforge.net/projects/oorexx) source repositories, mailing lists and 
other project features. Here is a list of some of the most useful facilities. 


The ooRexx Forums 


The ooRexx project maintains a set of forums that anyone may contribute to or monitor. They are 
located on the ooRexx Forums (http://sourceforge.net/forum/?group_id=119701) page. There are 
currently three forums available: Help, Developers and Open Discussion. In addition, you can 
monitor the forums via email. 


The Developer Mailing List 


You can subscribe to the oorexx-devel mailing list at ooRexx Mailing List Subscriptions 
(http://sourceforge.net/mail/?group_id=119701) page. This list is for discussing ooRexx project 
development activities and future interpreter enhancements. It also supports a historical archive of 
past messages. 


The Users Mailing List 


You can subscribe to the oorexx-users mailing list at ooRexx Mailing List Subscriptions 
(http://sourceforge.net/mail/?group_id=119701) page. This list is for discussing using ooRexx. It 
also supports a historical archive of past messages. 


The Announcements Mailing List 


You can subscribe to the oorexx-announce mailing list at ooRexx Mailing List Subscriptions 
(http://sourceforge.net/mail/?group_id=119701) page. This list is only used to announce significant 
ooRexx project events. 


The Bug Mailing List 


You can subscribe to the oorexx-bugs mailing list at ooRexx Mailing List Subscriptions 
(http://sourceforge.net/mail/?group_id=119701) page. This list is only used for monitoring changes 
to the ooRexx bug tracking system. 


Bug Reports 


You can create a bug report at ooRexx Bug Report 
(http://sourceforge.net/tracker/?group_id=119701 &atid=684730) page. Please try to provide as 
much information in the bug report as possible so that the developers can determine the problem as 
quickly as possible. Sample programs that can reproduce your problem will make it easier to debug 
reported problems. 


Request For Enhancement 
You can suggest ooRexx features at the ooRexx Feature Requests 
(http://sourceforge.net/tracker/?group_id=119701 &atid=684733) page. 
Patch Reports 


If you create an enhancement patch for ooRexx please post the patch using the ooRexx Patch Report 
(http://sourceforge.net/tracker/?group_id=119701 &atid=684732) page. Please provide as much 
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information in the patch report as possible so that the developers can evaluate the enhancement as 
quickly as possible. 


Please do not post bug patches here, instead you should open a bug report and attach the patch to it. 


3.3. comp.lang.rexx Newsgroup 


The comp.lang.rexx (news:comp.lang.rexx) newsgroup is a good place to obtain help from many 
individuals within the Rexx community. You can obtain help on Open Object Rexx or on any number of 
other Rexx interpreters and tools. 
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The Rexx language is particularly suitable for: 


* Application scripting 

* Command procedures 

* Application front ends 

* User-defined macros (such as editor subcommands) 
* Prototyping 


* Personal computing 


As an object-oriented language, Rexx provides data encapsulation, polymorphism, an object class 
hierarchy, class-based inheritance of methods, and concurrency. It includes a number of useful base 
classes and allows you create new object classes of your own. 


Open Object Rexx is compatible with earlier Rexx versions, both non-object based Rexx and IBM's 
Object Rexx. It has the usual structured-programming instructions, for example IF, SELECT, DO 
WHILE, and LEAVE, and a number of useful built-in functions. 


The language imposes few restrictions on the program format. There can be more than one clause on a 
line, or a single clause can occupy more than one line. Any indentation scheme is allowed. You can, 
therefore, code programs in a format that emphasizes their structure, making them easier to read. 


There is no limit to the size of variable values, as long as all values fit into the storage available. There 
are no restrictions on the types of data that variables can contain. 


A language processor (interpreter) runs Rexx programs. That is, the program runs line by line and word 
by word, without first being translated to machine language (compiled.) One of the advantages of this is 
that you can fix the error and rerun the program faster than when using a compiler. 


Note: Open Object Rexx also supplies the rexxc program that can be used to tokenize Rexx programs. 
Tokenizing a program is not the same as compiling a program to machine language. See Appendix A. 
Distributing Programs without Source of the Open Object Rexx Programming Guide for details on rexxc 
and tokenizing. 


1.1. What Is Object-Oriented Programming? 


Object-oriented programming is a way to write computer programs by focusing not on the instructions 
and operations a program uses to manipulate data, but on the data itself. First, the program simulates, or 
models, objects in the physical world as closely as possible. Then the objects interact with each other to 
produce the desired result. 


Real-world objects, such as a company's employees, money in a bank account, or a report, are stored as 
data so the computer can act upon it. For example, when you print a report, print is the action and report 
is the object acted upon. Essentially, the objects are the "nouns", while the actions are the "verbs". 


ooRexx Reference Version 4.0.0 1 


Chapter 1. Open Object Rexx General Concepts 


1.2. Modularizing Data 


In conventional, structured programming, actions like print are often isolated from the data by placing 
them in subroutines or modules. A module typically contains an operation for implementing one simple 
action. You might have a PRINT module, a SEND module, an ERASE module. The data these modules 
operate on must be constructed by the programmer and passed to the modules to perform an action. 


PROGRAM ... 

PRINT ----------------- 

ЕЕЕ data 

Sr аыдағы data data 
------------------------------- data 

data data dat 

ЕЕЕ data 529 
іі data diis 

SEND ---------------- data data 

оо даа 

ERASE -------------- 


But with object-oriented programming, it is the data that is modularized. And each data module includes 
its own operations for performing actions directly related to its data. The programmer that uses the 
objects need only be aware of the operations an object performs and not how the data is organized 


internally. 
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Figure 1-1. Modular Data—a Report Object 


PRINT 
Report 


data 
data 
data 
data 
data 


SEND 
а па 


ERASE 


In the case of report, the report object would contain its own built-in PRINT, SEND, ERASE, and FILE 
operations. 


Object-oriented programming lets you model real-world objects—even very complex ones—precisely 
and elegantly. As a result, object manipulation becomes easier and computer instructions become simpler 
and can be modified later with minimal effort. 


Object-oriented programming hides any information that is not important for acting on an object, thereby 
concealing the object’s complexities. Complex tasks can then be initiated simply, at a very high level. 


1.3. Modeling Objects 


In object-oriented programming, objects are modeled to real-world objects. A real-world object has 
actions related to it and characteristics of its own. 


Take a ball, for example. A ball can be acted on—rolled, tossed, thrown, bounced, caught. But it also has 
its own physical characteristics—size, shape, composition, weight, color, speed, position. An accurate 
data model of a real ball would define not only the physical characteristics but all related actions and 
characteristics in one package: 


ooRexx Reference Version 4.0.0 3 


Chapter 1. Open Object Rexx General Concepts 


Figure 1-2. A Ball Object 


BOUNCE 


Size 
Shape 
Comp 
Weight 
Color 
Speed 
Pos 


HOLVS | 


THROW 


| 


ROLL —— TOSS 


In object-oriented programming, objects are the basic building blocks—the fundamental units of data. 


There are many kinds of objects; for example, character strings, collections, and input and output 
streams. An object—such as a character string—always consists of two parts: the possible actions or 
operations related to it, and its characteristics or variables. A variable has a name, and an associated data 
value that can change over time. The variables represent the internal state of the object, and can be 
directly accessed only by the code that implements the object's actions. 


Figure 1-3. Ball Object with Variable Names and Values 


BOUNCE 

Size - 3 

Shape = round 
< Сошр = rubber 2 
Q Weight = 2 a 
E Color - yellow I 

Speed = 32 

Pos - 4 


ROLL —— TOSS 


To access an object's data, you must always specify an action. For example, suppose the object is the 
number 5. Its actions might include addition, subtraction, multiplication, and division. Each of these 
actions is an interface to the object's data. The data is said to be encapsulated because the only way to 
access it is through one of these surrounding actions. The encapsulated internal characteristics of an 
object are its variables. The variables are associated with an object and exist for the lifetime of that 
object: 
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Figure 1-4. Encapsulated 5 Object 
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1.4. How Objects Interact 


The actions defined by an object are its only interface to other objects. Actions form a kind of "wall" that 
encapsulates the object, and shields its internal information from outside objects. This shielding is called 
information hiding. Information hiding protects an object’s data from corruption by outside objects, and 
also protects outside objects from relying on another object’s private data, which can change without 


warning. 


One object can act upon another (or cause it to act) only by calling that object’s actions, namely by 
sending messages. Objects respond to these messages by performing an action, returning data, or both. A 
message to an object must specify: 


* A receiving object 
* The "message send" symbol, ~, which is called the twiddle 


* The action and, optionally in parentheses, any parameters required by the action 


So the message format looks like this: 

object^action(parameters) 

Assume that the object is the string ! iH. Sending it a message to use its REVERSE action: 
"АН" гетегве 


returns Ше string object Hi! . 
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1.5. Methods 


Sending a message to an object results in performing some action; that is, it executes some underlying 
code. The action-generating code is called a method. When you send a message to an object, the message 
is the name of the target method. Method names are character strings like REVERSE. In the preceding 
example, sending the reverse message to the ! iH object causes it to run the REVERSE method. Most 
objects are capable of more than one action, and so have a number of available methods. 


The classes Rexx provides include their own predefined methods. The Message class, for example, has 
the COMPLETED, INIT, NOTIFY, RESULT, SEND, and START methods. When you create your own 
classes, you can write new methods for them in Rexx code. Much of the object programming in Rexx is 
writing the code for the methods you create. 


1.6. Polymorphism 


Rexx lets you send the same message to objects that are different: 


"liH"^reverse /* Reverses the characters "!iH" to form "Hi!" */ 
pen^reverse /* Reverses the direction of a plotter pen ж/ 
ball^reverse /* Reverses the direction of a moving ball */ 


As long as each object has its own REVERSE method, REVERSE runs even if the programming 
implementation is different for each object. This ability to hide different functions behind a common 
interface is called polymorphism. As a result of information hiding, each object in the previous example 
knows only its own version of REVERSE. And even though the objects are different, each reverses itself 
as dictated by its own code. 


Although the ! iH object's REVERSE code is different from the plotter pen’s, the method name can be 
the same because Rexx keeps track of the methods each object owns. The ability to reuse the same 
method name so that one message can initiate more than one function is another feature of 
polymorphism. You do not need to have several message names like REVERSE STRING, 

REVERSE PEN, REVERSE BALL. This keeps method-naming schemes simple and makes complex 
programs easy to follow and modify. 


The ability to hide the various implementations of a method while leaving the interface the same 
illustrates polymorphism at its lowest level. On a higher level, polymorphism permits extensive code 
reuse. 


1.7. Classes and Instances 


In Rexx, objects are organized into classes. Classes are like templates; they define the methods and 
variables that a group of similar objects have in common and store them in one place. 


If you write a program to manipulate some screen icons, for example, you might create an Icon class. In 
that Icon class you can include all the icon objects with similar actions and characteristics: 
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Figure 1-5. A Simple Class 


Icon class 


Windows system icon instance 


shredder icon instance 
information icon instance 





All the icon objects might use common methods like DRAW or ERASE. They might contain common 
variables like position, color, or size. What makes each icon object different from one another is the data 
assigned to its variables. For the Windows system icon, it might be positionz "20,20", while for the 
shredder it is "20,30" and for information it is "20,40": 


Figure 1-6. Icon Class 


Icon class 


Windows system icon instance 
(position='20 ,20') 


shredder icon instance 
(position='20 ,30') 


information icon instance 
(position='20 ,40') 


Objects that belong to a class are called instances of that class. As instances of the Icon class, the 
Windows system icon, shredder icon, and information icon acquire the methods and variables of that 
class. Instances behave as if they each had their own methods and variables of the same name. All 
instances, however, have their own unique properties—the data associated with the variables. Everything 
else can be stored at the class level. 
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Figure 1-7. Instances of the Icon Class 


Icon class 
(position=) 


Windows system icon instance 
('20,20') 


shredder icon instance 
('20,30') 


information icon instance 
(20,40” 





If you must update or change a particular method, you only have to change it at one place, at the class 
level. This single update is then acquired by every new instance that uses the method. 


A class that can create instances of an object is called an object class. The Icon class is an object class 
you can use to create other objects with similar properties, such as an application icon or a drives icon. 


An object class is like a factory for producing instances of the objects. 


1.8. Data Abstraction 


The ability to create new, high-level data types and organize them into a meaningful class structure is 
called data abstraction. Data abstraction is at the core of object-oriented programming. Once you model 
objects with real-world properties from the basic data types, you can continue creating, assembling, and 
combining them into increasingly complex objects. Then you can use these objects as if they were part of 
the original programming language. 


1.9. Subclasses, Superclasses, and Inheritance 


When you write your first object-oriented program, you do not have to begin your real-world modeling 
from scratch. Rexx provides predefined classes and methods. From there you can create additional 
classes and methods of your own, according to your needs. 


Rexx classes are hierarchical. Any subclass (a class below another class in the hierarchy) inherits the 
methods and variables of one or more superclasses (classes above a class in the hierarchy): 
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Figure 1-8. Superclass and Subclasses 


Superclass 


Subclass Subclass Subclass 


You can add a class to an existing superclass. For example, you might add the Icon class to the 
Screen-Object superclass: 


Figure 1-9. The Screen-Object Superclass 


Screen-Object class 


Icon class Window class Bitmap class 


In this way, the subclass inherits additional methods from the superclass. A class can have more than one 
superclass, for example, subclass Bitmap might have the superclasses Screen-Object and Art-Object. 
Acquiring methods and variables from more than one superclass is known as multiple inheritance: 


Figure 1-10. Multiple Inheritance 


Screen-Object Art-Object 


Icon Window Bitmap 


1.10. Structure and General Syntax 


A Rexx program is built from a series of clauses that are composed of: 


* Zero or more whitespace characters (blank or horizontal tabs) (which are ignored) 

* A sequence of tokens (see Tokens) 

* Zero or more whitespace characters (again ignored) 

* Asemicolon (;) delimiter that the line end, certain keywords, or the colon (:) implies. 


Conceptually, each clause is scanned from left to right before processing, and the tokens composing it 
are identified. Instruction keywords are recognized at this stage, comments are removed, and sequences 
of whitespace characters (except within literal strings) are converted to single blanks. Whitespace 
characters adjacent to operator characters and special characters are also removed. 
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1.10.1. Characters 


A character is a member of a defined set of elements that is used for the control or representation of data. 
You can usually enter a character with a single keystroke. The coded representation of a character is its 
representation in digital form. A character, the letter A, for example, differs from its coded 
representation or encoding. Various coded character sets (such as ASCII and EBCDIC) use different 
encodings for the letter A (decimal values 65 and 193, respectively). This book uses characters to convey 
meanings and not to imply a specific character code, except where otherwise stated. The exceptions are 
certain built-in functions that convert between characters and their representations. The functions C2D, 
C2X, D2C, X2C, and XRANGE depend on the character set used. 


A code page specifies the encodings for each character in a set. Be aware that: 


* Some code pages do not contain all characters that Rexx defines as valid (for example, the logical 
NOT character). 


* Some characters that Rexx defines as valid have different encodings in different code pages, for 
example the exclamation mark (!). 


1.10.2. Whitespace 


A whitespace character is one that the interpreter recognizes as a "blank" or "space" character. There are 
two characters used by Rexx as whitespace that can be used interchangably: 


(blank) 


A "blank" or "space" character. This is represented by ’20’X in ASCII implementations. 


(horizontal tab) 
A "tab". This is represented by ’09’X in ASCII implementations. 


Horizontal tabs encountered in Rexx program source are converted into blanks, allowing tab characters 
and blanks to be use interchangeably in source. Additionally, Rexx operations such as the PARSE 
instruction or the SUBWORDY) built-in function will also accept either blank or tab characters as word 
delimiters. 


1.10.3. Comments 


A comment is a sequence of characters delimited by specific characters. It is ignored by the program but 
acts as a separator. For example, a token containing one comment is treated as two tokens. 


The interpreter recognizes the following types of comments: 


* Aline comment, where the comment is limited to one line 
* The standard Rexx comment, where the comment can cover several lines 


A line comment is started by two subsequent minus signs (--) and ends at the end of a line. Example: 
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"Fred" 
"Don't Panic!" 
'You shouldn't' -- Same as "You shouldn't" 


In this example, the language processor processes the statements from 'Fred' to 'You shouldn''t', ignores 
the words following the line comment, and continues to process the statement "". 


A standard comment is a sequence of characters (on one or more lines) delimited by /* and */. Within 
these delimiters any characters are allowed. Standard comments can contain other standard comments, as 
long as each begins and ends with the necessary delimiters. They are called nested comments. Standard 
comments can be anywhere and of any length. 


/* This is an example of a valid Rexx comment */ 


Take special care when commenting out lines of code containing /* or */ as part of a literal string. 
Consider the following program segment: 


01 parse pull input 

02 if substr(input,1,5) = "/*123" 
03 then call process 

04 dept = substr(input,32,5) 


To comment out lines 2 and 3, the following change would be incorrect: 


01 parse pull input 

02 /* if substr(input,1,5) - "/*123" 
03 then call process 

04 */ dept = substr(input,32,5) 


This is incorrect because the language processor would interpret the /* that is part of the literal string 
/*123 as the start of a nested standard comment. It would not process the rest of the program because it 
would be looking for a matching standard comment end (ж/). 


You can avoid this type of problem by using concatenation for literal strings containing /* or */; line 2 
would be: 


if substr(input,1,5) = "/" || "#123" 
You could comment out lines 2 and 3 correctly as follows: 


01 parse pull input 

02 /* if substr(input,1,5) = "/" || "#123" 
03 then call process 

04 */ dept = substr(input,32,5) 


Both types of comments can be mixed and nested. However, when you nest the two types, the type of 
comment that comes first takes precedence over the one nested. Here is an example: 


"Fred" 

"Don't Panic!" 

'You shouldn't' /* Same as "You shouldn't" 

i -- The null string ж/ 
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In this example, the language processor ignores everything after 'You shouldn''t' up to the end of the last 
line. In this case, the standard comment has precedence over the line comment. 


When nesting the two comment types, make sure that the start delimiter of the standard comment /ж is 
not in the line commented out with the line comment signs. 


Example: 


"Fred" 

"Don't Panic!" 

'You shouldn't' -- Same as /* "You shouldn't" 
ШЕ. The null string ж/ 


This example produces an error because the language processor ignores the start delimiter of the 
standard comment, which is commented out using the line comment. 


1.10.4. Tokens 


A token is the unit of low-level syntax from which clauses are built. Programs written in Rexx are 
composed of tokens. Tokens can be of any length, up to an implementation-restricted maximum. They 
are separated by whitespace or comments, or by the nature of the tokens themselves. The classes of 
tokens are: 


* Literal strings 

* Hexadecimal strings 
* Binary strings 

* Symbols 

* Numbers 

* Operator characters 


* Special characters 


1.10.4.1. Literal Strings 


A literal string is a sequence including any characters except line feed (X"10") and delimited by a single 
quotation mark (') or a double quotation mark ("). You use two consecutive double quotation marks ("") 
to represent one double quotation mark (") within a string delimited by double quotation marks. 
Similarly, you use two consecutive single quotation marks ('') to represent one single quotation mark (') 
within a string delimited by single quotation marks. A literal string is a constant and its contents are 
never modified when it is processed. Literal strings must be complete on a single line. This means that 
unmatched quotation marks can be detected on the line where they occur. 


A literal string with no characters (that is, a string of length 0) is called a null string. 


These are valid strings: 


"Fred" 
"Don't Panic!" 
'You shouldn't' /* Same as "You shouldn't" */ 
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me /* The null string ж/ 


Implementation maximum: А literal string has по upper bound оп the number of characters, limited 
on by available memory. 


Note that a string immediately followed by a left parenthesis is considered to be the name of a function. 
If immediately followed by the symbol X or x, it is considered to be a hexadecimal string. If followed 
immediately by the symbol B or b, it is considered to be a binary string. 


1.10.4.2. Hexadecimal Strings 


A hexadecimal string is a literal string, expressed using a hexadecimal notation of its encoding. It is any 
sequence of zero or more hexadecimal digits (0-9, a-f, A-F), grouped in pairs. A single leading 0 is 
assumed, if necessary, at the beginning of the string to make an even number of hexadecimal digits. The 
groups of digits are optionally separated by one or more whitespace characters, and the whole sequence 
is delimited by single or double quotation marks and immediately followed by the symbol X or x. Neither 
x nor X can be part of a longer symbol. The whitespace characters, which can only be byte boundaries 
(and not at the beginning or end of the string), are to improve readability. The language processor ignores 
them. 


A hexadecimal string is a literal string formed by packing the hexadecimal digits given. Packing the 
hexadecimal digits removes whitespace and converts each pair of hexadecimal digits into its equivalent 
character, for example, "41"X to A. 


Hexadecimal strings let you include characters in a program even if you cannot directly enter the 
characters themselves. These are valid hexadecimal strings: 


"ABCD"x 
"1d ec f8"X 
"1 d8"x 


Note: A hexadecimal string is not a representation of a number. It is an escape mechanism that lets 
a user describe a character in terms of its encoding (and, therefore, is machine-dependent). In 
ASCII, "20"X is the encoding for a blank. In every case, a string of the form "....."x is an alternative to 
a straightforward string. In ASCII "41"x and "A" are identical, as are "20"x and a blank, and must be 
treated identically. 


Implementation maximum: The packed length of a hexadecimal string (the string with whitespace 
removed) is unlimited. 


1.10.4.3. Binary Strings 


A binary string is a literal string, expressed using a binary representation of its encoding. It is any 
sequence of zero or more binary digits (0 or 1) in groups of 8 (bytes) or 4 (nibbles). The first group can 
have less than four digits; in this case, up to three 0 digits are assumed to the left of the first digit, making 
a total of four digits. The groups of digits are optionally separated by one or more whitespace characters, 
and the whole sequence is delimited by matching single or double quotation marks and immediately 
followed by the symbol b or B. Neither b nor B can be part of a longer symbol. The whitespace 
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characters, which can only be byte or nibble boundaries (and not at the beginning or end of the string), 
are to improve readability. The language processor ignores them. 


A binary string is a literal string formed by packing the binary digits given. If the number of binary digits 
is not a multiple of 8, leading zeros are added on the left to make a multiple of 8 before packing. Binary 
strings allow you to specify characters explicitly, bit by bit. These are valid binary strings: 


"11110000"b /ж == "£0"x xi 
"101 1101"b /ж == "Bd"x 7 
ae /* == "00000001"b and "01"х ж/ 
"10000 10101010"b /ж == "0001 0000 1010 1010"b */ 
нг; /ж == Ни ж/ 


Implementation maximum: The packed length of a binary-literal string is unlimited. 


1.10.4.4. Symbols 


Symbols are groups of characters, selected from the: 


* English alphabetic characters (A-Z and a-z). 
* Numeric characters (0-9) 
* Characters . ! ? and underscore (_). 


Any lowercase alphabetic character in a symbol is translated to uppercase (that is, lowercase a-z to 
uppercase A-Z) before use. 


These are valid symbols: 


Fred 
Albert.Hall 
WHERE? 


If a symbol does not begin with a digit or a period, you can use it as a variable and can assign it a value. 
If you have not assigned a value to it, its value is the characters of the symbol itself, translated to 
uppercase (that is, lowercase a-z to uppercase A-Z). Symbols that begin with a number or a period are 
constant symbols and cannot directly be assigned a value. (See Environment Symbols.) 


One other form of symbol is allowed to support the representation of numbers in exponential format. The 
symbol starts with a digit (0-9) or a period, and it can end with the sequence E or e, followed immediately 
by an optional sign (- or +), followed immediately by one or more digits (which cannot be followed by 
any other symbol characters). The sign in this context is part of the symbol and is not an operator. 


These are valid numbers in exponential notation: 


17.3E-12 
.03е-9 
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1.10.4.5. Numbers 


Numbers are character strings consisting of one or more decimal digits, with an optional prefix of a plus 
(+) or minus (-) sign, and optionally including a single period (.) that represents a decimal point. A 
number can also have a power of 10 suffixed in conventional exponential notation: an E (uppercase or 
lowercase), followed optionally by a plus or minus sign, then followed by one or more decimal digits 
defining the power of 10. Whenever a character string is used as a number, rounding can occur to a 
precision specified by the NUMERIC DIGITS instruction (the default is nine digits). See Numbers and 
Arithmetic for a full definition of numbers. 


Numbers can have leading whitespace (before and after the sign) and trailing whitespace. Whitespace 
characters cannot be embedded among the digits of a number or in the exponential part. Note that a 
symbol or a literal string can be a number. A number cannot be the name of a variable. 


These are valid numbers: 


12 

"—1T7. g" 
127.0650 
73e+128 

"+ T.9E5 " 


You can specify numbers with or without quotation marks around them. Note that the sequence -17.9 
(without quotation marks) in an expression is not simply a number. It is a minus operator (which can be 
prefix minus if no term is to the left of it) followed by a positive number. The result of the operation is a 
number, which might be rounded or reformatted into exponential form depending on the size of the 
number and the current NUMERIC DIGITS setting. 


A whole number is a number that has a no decimal part and that the language processor would not 
usually express in exponential notation. That is, it has no more digits before the decimal point than the 
current setting of NUMERIC DIGITS. 


Implementation maximum: The exponent of a number expressed in exponential notation can have up 
to nine digits. 


1.10.4.6. Operator Characters 


Thecharacters + - \ / 4 * | & = ~ > < and the sequences >= <= \> \< \= >< <> == No // && 
|| x => -< == === >> << >> \<< -<< V» =>> <<= indicate operations (see Operators). А 
few of these are also used in parsing templates, and the equal sign and the sequences +=, --, же /=, 
Як, //-, Пе, &, |=, and &&- are also used to indicate assignment. Whitespace characters adjacent 
to operator characters are removed. Therefore, the following are identical in meaning: 


345>=123 
345 >=123 
345 >= 123 
345 > = 123 


Some of these characters (and some special characters—see the next section) might not be available in 
all character sets. In this case, appropriate translations can be used. In particular, the vertical bar (1) is 
often shown as a split vertical bar (1). 
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Note: The Rexx interpreter uses ASCII character 124 in the concatenation operator and as the 
logical OR operator. Depending on the code page or keyboard for your particular country, ASCII 124 
сап be shown as a solid vertical bar (|) or a split vertical bar (|). The character on the screen might 
not match the character engraved on the key. If you receive error 13, Invalid character in program, 
on an instruction including a vertical bar character, make sure this character is ASCII 124. 


Throughout the language, the NOT (—) character is synonymous with the backslash (X). You can use 
the two characters interchangeably according to availability and personal preference. 


The Rexx interpreter recognizes both ASCII character 170 ( AA X) and ASCII character 172 ( AC' X) 
for the logical NOT operator. Depending on your country, the ^ might not appear on your keyboard. If 
the character is not available, you can use the backslash (V) in place of ~. 


1.10.4.7. Special Characters 


The following characters, together with the operator characters, have special significance when found 
outside of literal strings: 


>o 51202029 г” 


These characters constitute ше set of special characters. They all act as token delimiters, and whitespace 
characters (blank or horizontal tab) adjacent to any of these are removed. There is an exception: a 
whitespace character adjacent to the outside of a parenthesis or bracket is deleted only if it is also 
adjacent to another special character (unless the character is a parenthesis or bracket and the whitespace 
character is outside it, too). For example, the language processor does not remove the blank in A (Z). 
This is a concatenation that is not equivalent to A(Z), a function call. The language processor removes 
the blanks in (A) + (2) because this is equivalent to (A)+(Z). 


1.10.4.8. Example 


The following example shows how a clause is composed of tokens: 
"REPEAT" A+ 3; 


This example is composed of six tokens—a literal string ("REPEAT"), a blank operator, a symbol (A, 
which can have an assigned value), an operator (+), a second symbol (3, which is a number and a 
symbol), and the clause delimiter (;). The blanks between the A and the + and between the + and the 3 are 
removed. However, one of the blanks between the "REPEAT" and the A remains as an operator. Thus, this 
clause is treated as though written: 


"REPEAT" A+3; 


1.10.5. Implied Semicolons 


The last element in a clause is the semicolon (;) delimiter. The language processor implies the semicolon 
at a line end, after certain keywords, and after a colon if it follows a single symbol. This means that you 
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need to include semicolons only when there is more than one clause on a line or to end an instruction 
whose last character is a comma. 


A line end usually marks the end of a clause and, thus, Rexx implies a semicolon at most end of lines. 
However, there are the following exceptions: 


* The line ends in the middle of a comment. The clause continues on to the next line. 


* Thelast token was the continuation character (a comma or a minus sign) and the line does not end in 
the middle of a comment. (Note that a comment is not a token.) 


Rexx automatically implies semicolons after colons (when following a single symbol or literal string, a 
label) and after certain keywords when they are in the correct context. The keywords that have this effect 
are ELSE, OTHERWISE, and THEN. These special cases reduce typographical errors significantly. 


Note: The two characters forming the comment delimiters, / and «/, must not be split by a line end 
(that is, / and » should not appear on different lines) because they could not then be recognized 
correctly; an implied semicolon would be added. 


1.10.6. Continuations 


One way to continue a clause on the next line is to use the comma or the minus sign (-), which is referred 
to as the continuation character. The continuation character is functionally replaced by a blank, and, 
thus, no semicolon is implied. One or more comments can follow the continuation character before the 
end of the line. 


The following example shows how to use the continuation character to continue a clause: 


say "You can use a comma", -- this line is continued 
"to continue this clause." 


or 


say "You can use a minus"- -- this line is continued 
"to continue this clause." 


1.11. Terms, Expressions, and Operators 
Expressions in Rexx are a general mechanism for combining one or more pieces of data in various ways 
to produce a result, usually different from the original data. All expressions evaluate to objects. 


Everything in Rexx is an object. Rexx provides some objects, which are described in later sections. You 
can also define and create objects that are useful in particular applications—for example, a menu object 
for user interaction. See Modeling Objects for more information. 
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1.11.1. Terms and Expressions 


Terms are literal strings, symbols, message terms, function calls, or subexpressions interspersed with 
zero or more operators that denote operations to be carried out on terms. 


Literal strings, which are delimited by quotation marks, are constants. 


Symbols (no quotation marks) are translated to uppercase. A symbol that does not begin with a digit or a 
period can be the name of a variable; in this case the value of that variable is used. A symbol that begins 
with a period can identify an object that the current environment provides; in this case, that object is 
used. Otherwise a symbol is treated as a constant string. A symbol can also be compound. 


Message terms are described in Message Terms. 


Function calls (see Functions), which are of the following form: 


»»-symbolorstring(----4------------ %-%--)---------------------- >< 
%-ехргеввіоп-% 


The symbolorstring is а symbol or literal string. 


An expression consists of one or more terms. A subexpression is a term in an expression surrounded 
with a left and a right parenthesis. 


Evaluation of an expression is left to right, modified by parentheses and operator precedence in the usual 
algebraic manner (see Parentheses and Operator Precedence). Expressions are wholly evaluated, unless 
an error occurs during evaluation. 


As each term is used in an expression, it is evaluated as appropriate. The result is an object. 
Consequently, the result of evaluating any expression is itself an object (such as a character string). 


1.11.2. Operators 


An operator is a representation of an operation, such as an addition, to be carried out on one or two 
terms. Each operator, except for the prefix operators, acts on two terms, which can be symbols, strings, 
function calls, message terms, intermediate results, or subexpressions. Each prefix operator acts on the 
term or subexpression that follows it. Whitespace characters (and comments) adjacent to operator 
characters have no effect on the operator; thus, operators constructed from more than one character can 
have embedded whitespace and comments. In addition, one or more whitespace characters, if they occur 
in expressions but are not adjacent to another operator, also act as an operator. The language processor 
functionally translates operators into message terms. For dyadic operators, which operate on two terms, 
the language processor sends the operator as a message to the term on the left, passing the term on the 
right as an argument. For example, the sequence 


say 1+2 
is functionally equivalent to: 


say 17"+" (2) 
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The blank concatenation operator sends the message " " (a single blank), and the abuttal concatenation 
operator sends the "" message (a null string). When the - character is used in an operator, it is changed 
to a \. That is, the operators ~= and \= both send the message \= to the target object. 


For an operator that works on a single term (for example, the prefix - and prefix + operators), Rexx sends 
a message to the term, with no arguments. This means -z has the same effect as z^"-". 


See Operator Methods for operator methods of the Object class and Arithmetic Methods for operator 
methods of the String class. 


There are four types of operators: 


* Concatenation 
* Arithmetic 
* Comparison 


* Logical 


1.11.2.1. String Concatenation 


The concatenation operators combine two strings to form one string by appending the second string to 
the right-hand end of the first string. The concatenation may occur with or without an intervening blank. 
The concatenation operators are: 


(blank) Concatenate terms with one blank in between 
Il Concatenate without an intervening blank 


(abuttal) Concatenate without an intervening blank 


You can force concatenation without a blank by using the | | operator. 


The abuttal operator is assumed between two terms that are not separated by another operator. This can 
occur when two terms are syntactically distinct, such as a literal string and a symbol, or when they are 
only separated by a comment. 


Examples: 


An example of syntactically distinct terms is: if Fred has the value 37.4, then Fred"4" evaluates to 37.4%. 


If the variable PETER has the value 1, then (Fred) (Peter) evaluates to 37.41. 
The two adjoining strings, one hexadecimal and one literal, "Аа 4b"x"LMN" evaluate to JKLMN. 


In the case of 
Fred/* Тһе NOT operator precedes Peter. */—Peter 
there is no abuttal operator implied, and the expression is not valid. However, 


(Егед) /ж The NOT operator precedes Peter. */(—Peter) 


results in an abuttal, and evaluates to 37.40. 
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1.11.2.2. Arithmetic 


You can combine character strings that are valid numbers (see Numbers) using the following arithmetic 


operators: 

+ Add 

- Subtract 

# Multiply 

/ Divide 

% Integer divide (divide and return the integer part of the result) 
И Remainder (divide and return Ше remainder—not modulo, because Ше result can 

be negative) 

"S Power (raise a number to a whole-number power) 

Prefix - Same as the subtraction: 0 - number 

Prefix + Same as the addition: 0 + number 


See Numbers and Arithmetic for details about precision, the format of valid numbers, and the operation 
rules for arithmetic. Note that if an arithmetic result is shown in exponential notation, it is likely that 
rounding has occurred. 


1.11.2.3. Comparison 


The comparison operators compare two terms and return the value 1 if the result of the comparison is 
true, or 0 otherwise. 


The strict comparison operators all have one of the characters defining the operator doubled. The ==, 
\==, and —-- operators test for an exact match between two strings. The two strings must be identical 
(character by character) and of the same length to be considered strictly equal. Similarly, the strict 
comparison operators such as >> ог << carry out a simple character-by-character comparison, with 
no padding of either of the strings being compared. The comparison of the two strings is from left to 
right. If one string is shorter than the other and is a leading substring of another, then it is smaller than 
(less than) the other. The strict comparison operators also do not attempt to perform a numeric 
comparison on the two operands. 


For all other comparison operators, if both terms involved are numeric, a numeric comparison (see 
Numeric Comparisons) is effected. Otherwise, both terms are treated as character strings, leading and 
trailing whitespace characters are ignored, and the shorter string is padded with blanks on the right. 


Character comparison and strict comparison operations are both case-sensitive, and the exact collating 
order might depend on the character set used for the implementation. In an ASCII environment, such as 
Windows and *nix, the ASCII character value of digits is lower than that of the alphabetic characters, 
and that of lowercase alphabetic characters is higher than that of uppercase alphabetic characters. 


The comparison operators and operations are: 


= True if the terms are equal (numerically or when padded) 
\=, == True if the terms are not equal (inverse of =) 


^ 


> Greater than 
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< Less than 

>< Greater than or less than (same as not equal) 
<> Greater than or less than (same as not equal) 
>= Greater than or equal to 

че Not less than 

<= Less than or equal to 

\, => Not greater than 

== True if terms are strictly equal (identical) 
M, === True if the terms are not strictly equal (inverse of == 
>> Strictly greater than 

<< Strictly less than 

>>= Strictly greater than or equal to 

\<<, n<< Strictly not less than 

<<= Strictly less than or equal to 

\>>, =>> Strictly not greater than 


Note: Throughout the language, the NOT (-) character is synonymous with the backslash(\). You 
can use the two characters interchangeably, according to availability and personal preference. The 
backslash can appear in the following operators: \ (prefix not), \=, \==, \<, V», \<<, and Vo». 


1.11.2.4. Logical (Boolean) 


A character string has the value false if it is 0, and true if it is 1. The logical operators take one or two 
such values and return 0 or 1 as appropriate. Values other than 0 or 1 are not permitted. 


& AND — returns 1 if both terms are true. 

| Inclusive OR — returns 1 if either term or both terms are true. 

«е Exclusive ОК — returns 1 if either term, but not both terms, is true. 
Prefix V, = Logical NOT— negates; 1 becomes 0, and 0 becomes 1. 


1.11.3. Parentheses and Operator Precedence 


Expression evaluation is from left to right; parentheses and operator precedence modify this: 


* When parentheses are encountered—other than those that identify the arguments on messages (see 
Message Terms) and function calls—the entire subexpression between the parentheses is evaluated 


immediately when the term is required. 


* When the sequence 
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termi operatori term2 operator2 term3 


is encountered, and operator2 has precedence over operator1, the subexpression (term2 operator2 


term3) is evaluated first. 


Note, however, that individual terms are evaluated from left to right in the expression (that is, as soon 
as they are encountered). The precedence rules affect only the order of operations. 


For example, * (multiply) has a higher priority than + (add), so 3+2*5 evaluates to 13 (rather than the 25 
that would result if a strict left-to-right evaluation occurred). To force the addition to occur before the 
multiplication, you could rewrite the expression as (3+2) *5. Adding the parentheses makes the first three 
tokens a subexpression. Similarly, the expression -Зжж2 evaluates to 9 (instead of -9) because the prefix 
minus operator has a higher priority than the power operator. 


The order of precedence of the operators is (highest at the top): 


~ M 
+ - = \ 
жж 

ж 1 % I 
ge «e 
(blank) |l 
=>< 
== >> << 


(abuttal) 


\ a= 
>< <> 
\> -> 
\< -< 


а үлек мес 


\>> ->> 
\<< -<< 
>= >>= 
<= <<= 


| && 


Examples: 


(message send) 

(prefix operators) 

(power) 

(multiply and divide) 

(add and subtract) 

(concatenation with or without blank) 


(comparison operators) 


(and) 


(or, exclusive or) 


Suppose the symbol A is a variable whose value is 3, DAY is a variable whose value is Monday, and other 


variables are uninitialized. 
А+5 -> 
A-4*2 -> 
A/2 -> 
0.5**2 -> 
(A+1)>7 -» 
" "aun -» 


Then: 
"gu 
.... 
"1.5" 
"0.25" 
"о" /* that is, False */ 
“1. /* that is, True ж/ 
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È" "=="! -> "о" /* that is, False */ 
" "\==" Ш -> "1" 

/* that is, True */ 

(А+1) *3=12 -> тан /* that is, True ж/ 
"077">"11" -> WD /* that is, True ж/ 
"O77" >> "11" -> "о" /* that is, False */ 
"abc" >> "ab" -> "qu /* that is, True ж/ 
"abc" «« "abd" -> "pt /* that is, True ж/ 
"ab " << "abd" -> da ka /* that is, True ж/ 
Today is Day -> "TODAY IS Monday" 

"If it is" day -> "If it is Monday" 
Substr(Day,2,3) -> "ond" /* Substr is a function */ 
5.60 -> "IXXX!" 


Note: The Rexx order of precedence usually causes no difficulty because it is the same as in 
conventional algebra and other computer languages. There are two differences from common 
notations: 


* The prefix minus operator always has a higher priority than the power operator. 


* Power operators (like other operators) are evaluated from left to right. 


For example: 

-Зжж2 == 9 /ж not -9 ж/ 
-(241)**2 == 9 /ж not -9 */ 
2Жж2ЖжЖ3- == 64 /ж not 256 */ 


1.11.4. Message Terms 


You can include messages to objects in an expression wherever a term, such as a literal string, is valid. A 
message can be sent to an object to perform an action, obtain a result, or both. 


A message term can have one of the following forms: 


>>-гесеіуек-%- ^ --+-шеѕѕарепаше--+--------- Wem a a Sessa, > 
aS mE +-:symbol-+ 
>--%--------------------------%-------------------------------- >< 
%-(------------------- +--)-+ 
| gos жыла тора + | 
lv | | 
+---expression-+-+ 
»»-receiver[--4---------------- o-[-—-——---22-2----29-----—-— >< 
| +-,---------- + | 
| v Iu 


+---expression-+-+ 
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The receiver is a term (see Terms and Expressions for a definition of term). It receives the message. The 
~ or ~~ indicates sending a message. The messagename is a literal string or a symbol that is taken as a 
constant. The expressions (separated by commas) between the parentheses or brackets are the arguments 
for the message. The receiver and the argument expressions can themselves include message terms. If the 
message has no arguments, you can omit the parentheses. 


The left parenthesis, if present, must immediately follow a token (messagename or symbol) with no 
blank in between them. Otherwise, only the first part of the construct is recognized as a message term. (A 
blank operator would be assumed at that point.) Only a comment (which has no effect) can appear 
between a token and the left parenthesis. 


You can use any number of expressions, separated by commas. The expressions are evaluated from left to 
right and form the arguments during the execution of the called method. Any ARG, PARSE ARG, or 
USE ARG instruction or ARG() built-in function in the called method accesses these objects while the 
called method is running. You can omit expressions, if appropriate, by including extra commas. 


The receiver object is evaluated, followed by one or more expression arguments. The message name (in 
uppercase) and the resulting argument objects are then sent to the receiver object. The receiver object 
selects a method to be run based on the message name (see Classes and Inheritance), and runs the 
selected method with the specified argument objects. The receiver eventually returns, allowing 
processing to continue. 


If the message term uses ~, the receiver method must return a result object. This object is included in the 
original expression as if the entire message term had been replaced by the name of a variable whose 
value is the returned object. 


For example, the message POS is valid for strings, and you could code: 


c="escape" 
a="Position of "е! is:" c^pos("e",3) 
/* would set A to "Position of "е! is: 6" */ 


If the message term uses ~~, the receiver method need not return a result object. Any result object is 
discarded, and the receiver object is included in the original expression in place of the message term. 


For example, the messages INHERIT and SUBCLASS are valid for classes (see The Class Class) and, 
assuming the existence of the Persistent class, you could code: 


account = .object^subclass("Account")^^inherit(.persistent) 
/* would set ACCOUNT to the object returned by SUBCLASS, */ 
/* after sending that object the message INHERIT */ 


If the message term uses brackets, the message [] is sent to the receiver object. (The expressions within 
the brackets are available to the receiver object as arguments.) The effect is the same as for the 
corresponding ~ form of the message term. Thus, а [Ы] is the same as a^" []" (b). 


For example, the message [] is valid for arrays (see The Array Class) and you could code: 
a = .array^of(10,20) 
say "Second item is" a[2] /* Same as: a^at(2) ж/ 


/* or a^"[]"(2) */ 


/* Produces: "Second item is 20" */ 
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A message can have a variable number of arguments. You need to specify only those required. For 
example, "ESCAPE" "POS ("E") returns 1. 


A colon (:) and symbol can follow the message name. In this case, the symbol must be the name of a 
variable (usually the special variable SUPER--see page SUPER) or an environment symbol (see 
Environment Symbols). The resulting value changes the usual method selection. For more information, 
see Changing the Search Order for Methods. 


1.11.5. Message Sequences 


The ~ and ~~ forms of message terms differ only in their treatment of the result object. Using ^ returns 
the result of the method. Using ^^ returns the object that received the message. Here is an example: 


/* Two ways to use the INSERT method to add items to a list */ 
/* Using only ^ */ 

team - .list^of("Bob","Mary") 

team^insert("Jane") 

team^insert("Joe") 

team^insert("Steve") 


say "First on the team is:" team^firstitem /* Bob */ 
say "Last on the team is:" team^lastitem /* Steve */ 
/* Do the same thing using ^^ */ 
team-.list^of("Bob","Mary") 

/* Because ^^ returns the receiver of the message ж/ 
/* each INSERT message following returns the list ж/ 
/* object (after inserting the argument value). ж/ 
team~~ insert ("Jane") ~~ insert ("Joe") ~~insert ("Steve") 

say "First on the team is:" team^firstitem /* Bob */ 
say "Last on the team is:" team^lastitem /* Steve */ 


Thus, you would use - when you want the returned result to be the receiver of the next message in the 
sequence. 


1.12. Clauses and Instructions 


Clauses can be subdivided into the following types: 


* Null clauses 

* Directives 

* Labels 

* Instructions 

* Assignments 

* Message instructions 


* Keyword instructions 
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* Commands 


1.12.1. Null Clauses 


A clause consisting only of whitespace characters, comments, or both is a null clause. It is completely 
ignored. 


Note: A null clause is not an instruction; for example, putting an extra semicolon after the THEN or 
ELSE in an IF instruction is not equivalent to using a dummy instruction (as it would be in the C 
language). The NOP instruction is provided for this purpose. 


1.12.2. Directives 


A clause that begins with two colons is a directive. Directives are nonexecutable code and can start in 
any column. They divide a program into separate executable units (methods and routines) and supply 
information about the program or its executable units. Directives perform various functions, such as 
creating new Rexx classes (::CLASS directive) or defining a method (:: METHOD directive). See 
Directives for more information about directives. 


1.12.3. Labels 


A clause that consists of a single symbol or string followed by a colon is a label. The colon in this 
context implies a semicolon (clause separator), so no semicolon is required. 


The label’s name is taken from the string or symbol part of the label. If the label uses a symbol for the 
name, the label's name is in uppercase. If a label uses a string, the name can contain mixed-case 
characters. 


Labels identify the targets of CALL instructions, SIGNAL instructions, and internal function calls. Label 
searches for CALL, SIGNAL, and internal function calls are case-sensitive. Label-search targets 
specified as symbols cannot match labels with lowercase characters. Literal-string or computed-label 
searches can locate labels with lowercase characters. 


Labels can be any number of successive clauses. Several labels can precede other clauses. Labels are 
treated as null clauses and can be traced selectively to aid debugging. 


Duplicate labels are permitted, but control is only passed to the first of any duplicates in a program. The 
duplicate labels occurring later can be traced but cannot be used as a target of a CALL, SIGNAL, or 
function invocation. 
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1.12.4. Instructions 


An instruction consists of one or more clauses describing some course of action for the language 
processor to take. Instructions can be assignments, message instructions, keyword instructions, or 
commands. 


1.12.5. Assignments 


A single clause of the form symbol=expression is an instruction known as an assignment. An assignment 
gives a (new) value to a variable. See Assignments and Symbols. 


1.12.5.1. Extended Assignments 


The character sequences +=, --, же /=, %=, //=, И, &=, |=, and &&=can be used to create 
extended assignments. These sequences combine an operation with the assignment. See Extended 
Assignments for more details. 


1.12.5.2. Message Instructions 


A message instruction is a single clause in the form of a message term (see Message Terms) or in the 
form messageterm=expression. A message is sent to an object, which responds by performing some 
action. See Message Instructions. 


1.12.5.3. Keyword Instructions 


A keyword instruction is one or more clauses, the first of which starts with a keyword that identifies the 
instruction. Keyword instructions control, for example, the external interfaces and the flow of control. 
Some keyword instructions can include nested instructions. In the following example, the DO construct 
(DO, the group of instructions that follow it, and its associated END keyword) is considered a single 
keyword instruction. 


DO 
instruction 
instruction 
instruction 

END 


A subkeyword is a keyword that is reserved within the context of a particular instruction, for example, the 
symbols TO and WHILE in the DO instruction. 


1.12.6. Commands 


A command is a clause consisting of an expression only. The expression is evaluated and the result is 
passed as a command string to an external environment. 
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1.13. Assignments and Symbols 


A variable is an object whose value can change during the running of a Rexx program. The process of 
changing the value of a variable is called assigning a new value to it. The value of a variable is a single 
object. Note that an object can be composed of other objects, such as an array or directory object. 


You can assign a new value to a variable with the ARG, PARSE, PULL, or USE instructions, the VALUE 
built-in function, or the but the most common way of changing the value of a variable is the assignment 
instruction itself. Any clause in the form 


symbol=expression; 


is taken to be an assignment. The result of expression becomes the new value of the variable named by 
the symbol to the left of the equal sign. 


Example: 


/* Next line gives FRED the value "Frederic" */ 
Fred="Frederic" 


The symbol naming the variable cannot begin with a digit (0-9) or a period. 


You can use a symbol in an expression even if you have not assigned a value to it, because a symbol has 
a defined value at all times. A variable to which you have not assigned a value is uninitialized. Its value 
is the characters of the symbol itself, translated to uppercase (that is, lowercase a-z to uppercase A-Z). 
However, if it is a compound symbol (described under Compound Symbols), its value is the derived 
name of the symbol. 


Example: 

/* If Freda has not yet been assigned a value, ж/ 
/* then next line gives FRED the value "FREDA"  */ 
Fred-Freda 


The meaning of a symbol in Rexx varies according to its context. As a term in an expression, a symbol 
belongs to one of the following groups: constant symbols, simple symbols, compound symbols, 
environment symbols, and stems. Constant symbols cannot be assigned new values. You can use simple 
symbols for variables where the name corresponds to a single value. You can use compound symbols and 
stems for more complex collections of variables although the collection classes might be preferable in 
many cases. See The Collection Classes. 


1.13.1. Extended Assignments 


The character sequences +=, --, же /-, %=, //=, И, &=, |=, and &&- can be used to create 
extended assignment instructions. An extended assignment combines a non-prefix operator with an 
assignment where the term on the left side of the assignment is also used as the left term of the operator. 
For example, 


а += 1 


is exactly equivalent to the instruction 
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Extended assignments are processed identically to the longer form of the instruction. 


1.13.2. Constant Symbols 


A constant symbol starts with a digit (0-9) or a period. 


You cannot change the value of a constant symbol. It is simply the string consisting of the characters of 
the symbol (that is, with any lowercase alphabetic characters translated to uppercase). 


These are constant symbols: 


77 

827.53 

.12345 

12е5 /* Same as 12E5 ж/ 
3D 

17E-3 


Symbols where the first character is a period and the second character is alphabetic are environment 
symbols. Environment symbols). may have a value other other than the symbol name. 


1.13.3. Simple Symbols 


A simple symbol does not contain any periods and does not start with a digit (0-9). 


By default, its value is the characters of the symbol (that is, translated to uppercase). If the symbol has 
been assigned a value, it names a variable and its value is the value of that variable. 


These are simple symbols: 


FRED 
Whatagoodidea? /* Same as WHATAGOODIDEA? */ 
712 


1.13.4. Stems 


A stem is a symbol that contains a single period as the last character of the name. It cannot start with a 
digit. 
These are stems: 


FRED. 
A. 


The value of a stem is always a Stem object. (See The Stem Class.) The stem variable's Stem object is 
automatically created the first time you use the stem variable or a compound variable) containing the 
stem variable name. The Stem object's assigned name is the name of the stem variable (with the 
characters translated to uppercase). If the stem variable has been assigned a value, or the Stem object has 
been given a default value, the assigned name override the default stem name. A reference to a stem 
variable will return the associate Stem object. 
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When a stem is the target of an assignment, the action taken depends on the value being assigned. If the 
new value is a Stem object, the new Stem object will replace the the Stem object that is currently 
associated with the stem variable. This can result in multiple stem variables referring to a the same Stem 
object, effectively creating a variable alias. 


Example: 
hole. - "empty" 
hole.19 - "full" 


say hole.1 hole.mouse hole.19 
/* Says "empty empty full" ж/ 


hole2. = hole. /* copies reference to hole. stem to hole2. */ 

say hole2.1 hole2.mouse hole2.19 

/* Also says "empty empty full" ж/ 

If the new value is not a Stem object, a new Stem object is created and assigned to the stem variable, 


replacing the Stem object currently associated with the stem variable. 


The new value assigned to the stem variable is given to the new Stem object as a default value. Following 
the assignment, a reference to any compound symbol with that stem variable returns the new value until 
another value is assigned to the stem, the Stem object, or the individual compound variable. 


Example: 


hole. = "empty" 

hole.19 - "full" 

say hole.1 hole.mouse hole.19 
/* says "empty empty full" ж/ 


Thus, you can initialize an entire collection of compound variables to the same value. 


You can pass stem collections as function, subroutine, or method arguments. 


Example: 


/* CALL RANDOMIZE count, stem. calls routine */ 
Randomize: Use Arg count, stem. 
do i = 1 to count 
stem.i = random(1,100) 
end 
return 


The USE ARG instruction functions as an assignment instruction. The variable STEM. in the example 
above is functionally equivalent to: 


stem. - arg(2) 


Note: USE ARG must be used to access the stem variable as a collection. PARSE and PARSE ARG 
will force the stem to be a string value. 
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Stems can also be returned as function, subroutine, or method results. The resulting return value is the 
Stem object associated with the stem variable. 


Example: 


/* RANDOMIZE(count) calls routine */ 
Randomize: Use Arg count 
do i = i to count 
stem.i = random(1,100) 
end 
return stem. 


When a stem. variable is used in an expression context, the stem variable reference returns the associated 
Stem object. The Stem object will forward many object messages to it’s default value. For example, the 
STRING method will return the Stem object’s default value’s string representation: 


total. = 0 
say total. /* says "0" */ 


The [] method with no arguments will return the currently associated default value. variables can always 
be obtained by using the stem. However, this is not the same as using a compound variable whose 
derived name is the null string. 


total. = 0 

null = "" 

total.null - total.null * 5 

say total.[] total.null /* says "0 5" x/ 


You can use the DROP, EXPOSE, and PROCEDURE instructions to manipulate collections of variables, 
referred to by their stems. DROP FRED. assigns a new Stem object to the specified stem. (See DROP.) 
EXPOSE FRED. and PROCEDURE EXPOSE FRED. expose all possible variables with that stem (see EXPOSE 
and PROCEDURE). 


The DO instruction can also iterate over all of the values assigned to a stem variable. See DO for more 
details. 


Notes: 


1. When the ARG, PARSE, PULL, or USE instruction, the VALUE built-in function, or the variable 
pool interface changes a variable, the effect is identical with an assignment. 


2. Any clause that starts with a symbol and whose second token is (or starts with) an equal sign (=) is 
an assignment, rather than an expression (or a keyword instruction). This is not a restriction, because 
you can ensure that the clause is processed as a command, such as by putting a null string before the 
first name, or by enclosing the expression in parentheses. 


If you unintentionally use a Rexx keyword as the variable name in an assignment, this should not 
cause confusion. For example, the following clause is an assignment, not an ADDRESS instruction: 
Address-"10 Downing Street"; 

3. You can use the VAR function (see VAR) to test whether a symbol has been assigned a value. In 
addition, you can set SIGNAL ON NOVALUE to trap the use of any uninitialized variables (except 


when they are tails in compound variables or stem variables, which are always initialized with a 
Stem object when first used. 
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1.13.5. Compound Symbols 


A compound symbol contains at least one period and two other characters. It cannot start with a digit or a 
period, and if there is only one period it cannot be the last character. 


The name begins with a stem (that part of the symbol up to and including the first period) and is followed 
by a tail, which are parts of the name (delimited by periods) that are constant symbols, simple symbols, 
or null. Note that you cannot use constant symbols with embedded signs (for example, 12.3E+5) after a 
stem; in this case the whole symbol would not be valid. 


These are compound symbols: 


FRED .3 
Array.I.J 
AMESSY. .One.2. 


Before the symbol is used, that is, at the time of reference, the language processor substitutes in the 
compound symbol the character string values of any simple symbols in the tail (I, J, and One in the 
examples), thus generating a new, derived tail. The value of a compound symbol is, by default, its the 
name of the Stem object associated with the stem variable concatenated to the derived tail or, if it has 
been used as the target of an assignment, the value of Stem element named by the derived tail. 


The substitution in the symbol permits arbitrary indexing (subscripting) of collections of variables that 
have a common stem. Note that the values substituted can contain any characters (including periods and 
blanks). Substitution is done only once. 


More formally, the derived name of a compound variable that is referenced by the symbol 


50.51.52. --- .sn 
is given by 
dO.vi.v2. --- „уа 


where 40 is the name of the Stem object associated with the stem variable sO and v1 to vn are the values 
of the constant or simple symbols s1 through sn. Any of the symbols s1 to sn can be null. The values v1 
to vn can also be null and can contain any characters (including periods). Lowercase characters are not 
translated to uppercase, blanks are not removed, and periods have no special significance. There is no 
limit on the length of the evaluated name. 


Some examples of simple and compound symbols follow in the form of a small extract from a Rexx 


program: 
a-3 /* assigns "3" to the variable A ж/ 
2-4 /ж "4" to 2 ж/ 
с= "Егей" /* "Fred" toC ж/ 
a.z="Fred" /* "Fred" to A.4 ж/ 
a.fred=5 /* "Б" to A.FRED ж/ 
a.c-"Bill" /* "Bill" to A.Fred ж/ 
c.c=a.fred /ж "5" to C.Fred  */ 
y.a.z-"Annie" /* "Annie" to Y.3.4 ж/ 
say а 2 с a.a a.z а.с c.a a.fred y.a.4 

/* displays the string: ж/ 

/ж "3 4 Fred А.З Fred Bill C.3 5 Annie" ж/ 
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You can use compound symbols to set up arrays and lists of variables in which the subscript is not 
necessarily numeric, thus offering a great scope for the creative programmer. A useful application is to 
set up an array in which the subscripts are taken from the value of one or more variables, producing a 
form of associative memory (content-addressable). 


1.13.5.1. Evaluated Compound Variables 


The value of a stem variable is always a Stem object (see The Stem Class for details). A Stem object is a 
type of collection that supports the [] and []= methods used by other collection classes. The || method 
provides an alternate means of accessing compound variables that also allows embedded subexpressions. 


Examples: 

a-3 /* assigns "3" to the variable A ж/ 
2-4 /ж "4" to Z */ 
c="Fred" /* "Fred" toC ж/ 
а. [z]="Fred" /* "Fred" to A.4 ж/ 
а. [z+1]="Rick" /* "Rick" to A.5 ж/ 
а. [fred]=5 /ж "gr to A.FRED */ 
а. [с]="Ві11" /ж "Ві11" to A.Fred ж/ 
c. [c]=a.fred /* "5" to C.Fred */ 
у. [а,2]="Аппіе" /* "Annie" to Y.3.4 ж/ 


say а 2 с а. [а] а. [2] а. [2+1] 

а. [<] с. [а] a.[fred] у. [а, ғ] 

/* displays the string: ж/ 

/ж "3 4 Fred А.З Fred Rick Bill С.З 5 Annie" ж/ 


1.13.6. Environment Symbols 


An environment symbol starts with a period and has at least one other character. This character must not 
be a digit. By default the value of an environment symbol is the string consisting of the characters of the 
symbol (translated to uppercase). If the symbol identifies an object in the current environment, its value 

is the mapped object. 


These are environment symbols: 


.method // A reference to the Rexx Method class 
.true // The Rexx "true" object. Has the value "1" 
.XyZ // Normally the value .XYZ 


When you use an environment symbol, the language processor performs a series of searches to see if the 
environment symbol has an assigned value. The search locations and their ordering are: 


1. The directory of classes declared on ::CLASS directives (see ::CLASS) within the current program 
package or added to the current package using the addClass() method. 
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2. The directory of PUBLIC classes declared on ::CLASS directives of other files included with a 
: REQUIRES directive or added to the current Package instance using the addPackage() method. 


3. The local environment directory specific to the current interpreter instance. The local environment 
includes process-specific objects such as the INPUT and .OUTPUT objects. You can directly access 
the local environment directory by using the LOCAL environment symbol. (See The Local 
Environment Object (.LOCAL).) 


4. The global environment directory. The global environment includes all permanent Rexx objects such 
as the Rexx supplied classes (.ARRAY and so on) and constants such as .TRUE and .FALSE. You 
can directly access the global environment by using the ENVIRONMENT environment symbol (see 
The Environment Object). Entries in the global environment directory can also be accessed via the 
VALUE built-in function (see VALUE) by using a null string for the selector argument. 


Nn 


. Rexx defined symbols. Other simple environment symbols are reserved for use by Rexx built-in 
environment objects. The currently defined built-in objects are .RS, LINE, . METHODS, 
-ROUTINES, and .CONTEXT. 


If an entry is not found for an environment symbol, then the default character string value is used. 


Note: You can place entries in both the LOCAL and the .ENVIRONMENT directories for programs to 
use. To avoid conflicts with future Rexx defined entries, it is recommended that the entries that you 
place in either directory include at least one period in the entry name. 


Example: 


/* establish settings directory */ 
.local^setentry("MyProgram.settings", .directory^new) 


1.14. Message Instructions 


You can send a message to an object to perform an action, obtain a result, or both. You use a message 
instruction if the main purpose of the message is to perform an action. You use a message term (see 
Message Terms) if the main purpose of the message is to obtain a result. 


A message instruction is a clause of the form: 


2»-messageterm--*------------- Poa SSS Sasa SaaS Sasa Sasa SS ae assess >< 
+-=expression-+ 


If there is only a messageterm, the message is sent in exactly the same way as for a message term (see 
Message Terms). If the message yields a result object, it is assigned to the sender’s special variable 
RESULT. If you use the ~~ form of message term, the receiver object is used as the result. If there is no 
result object, the variable RESULT is dropped (becomes uninitialized). A message term using ~~ is 
sometimes referred to as a cascading message. 


Example: 
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mytable~add("John" , 123) 
This sends the message ADD to the object MYTABLE. The ADD method need not return a result. If 


ADD returns a result, the result is assigned to the variable RESULT. 


The equal sign (=) sets a value. If expression follows the message term, a message is sent to the 
receiver object with an = concatenated to the end of the message name. The result of evaluating the 
expression is passed as the first argument of the message. 


Example: 
person^age - 39 /* Same as person^"AGE-"(39) */ 
table[i] = 5 /* Same ав table^"[]-"(5,i) ж/ 


The expressions are evaluated in the order in which the arguments are passed to the method. That is, the 
language processor evaluates Ше =expression first. Then it evaluates the argument expressions within 
any [] pairs from left to right. 


The extended assignment form may also be used with messaging terms. 


Example: 
table[i] += 1 -- Same as table[i] = table[i] + 1 


See Extended Assignments for more details 


1.15. Commands to External Environments 


Issuing commands to the surrounding environment is an integral part of Rexx. 


1.15.1. Environment 


The base system for the language processor is assumed to include at least one environment for 
processing commands. An environment is selected by default on entry to a Rexx program. You can 
change the environment by using the ADDRESS instruction. You can find out the name of the current 
environment by using the ADDRESS built-in function. The underlying operating system defines 
environments external to the Rexx program. The environments selected depend on the caller. Normally 
the default environment is the used shell, mostly "CMD" on Windows systems and "bash" on Linux 
systems. If called from an editor that accepts subcommands from the language processor, the default 
environment can be that editor. 


A Rexx program can issue commands—called subcommands—to other application programs. For 
example, a Rexx program written for a text editor can inspect a file being edited, issue subcommands to 
make changes, test return codes to check that the subcommands have been processed as expected, and 
display messages to the user when appropriate. 


An application that uses Rexx as a macro language must register its environment with the Rexx language 
processor. See the Open Object Rexx: Programming Guide for a discussion of this mechanism. 
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1.15.2. Commands 


To send a command to the currently addressed environment, use a clause of the form: 
expression; 


The expression (which must not be an expression that forms a valid message instruction—see Message 
Instructions) is evaluated, resulting in a character string value (which can be the null string), which is 
then prepared as appropriate and submitted to the environment specified by the current ADDRESS 
setting. 


The environment then processes the command and returns control to the language processor after setting 
areturn code. A return code is a string, typically a number, that returns some information about the 
command processed. A return code usually indicates if a command was successful but can also represent 
other information. The language processor places this return code in the Rexx special variable RC. See 
Special Variables. 


In addition to setting a return code, the underlying system can also indicate to the language processor if 
an error or failure occurred. An error is a condition raised by a command to which a program that uses 
that command can respond. For example, a locate command to an editing system might report requested 
string not found as ап error. A failure is a condition raised by a command to which a program that 
uses that command cannot respond, for example, a command that is not executable or cannot be found. 


Errors and failures in commands can affect Rexx processing if a condition trap for ERROR or FAILURE 
is ON (see Conditions and Condition Traps). They can also cause the command to be traced if TRACE E 
Or TRACE F is set. TRACE Normal is the same as TRACE F and is the default—see TRACE. 


The .RS environment symbol can also be used to detect command failures and errors. When the 
command environment indicates that a command failure has occurred, the Rexx environment symbol .RS 
has the value -1. When a command error occurs, .RS has a value of 1. If the command did not have a 
FAILURE or ERROR condition, .RS is 0. 


Here is an example of submitting a command. Where the default environment is Windows, the sequence: 


"CHESHIRE" 
exten "CAT" 
"TYPE" fname"."exten 


fname 


would result in passing the string TYPE CHESHIRE.CAT to the command processor, CMD.EXE. The 
simpler expression: 


"TYPE CHESHIRE.CAT" 


has the same effect. 


On return, the return code placed in RC will have the value 0 if the file CHESHIRE.CAT were typed, or a 
nonzero value if the file could not be found in the current directory. 


Note: Remember that the expression is evaluated before it is passed to the environment. Constant 
portions of the command should be specified as literal strings. 


Windows Example: 
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delete "*".1st /* not "multiplied by" */ 
var.003 = anyvalue 

type "var.003" /* not a compound symbol */ 
w = any 

dir"/w" /* not "divided by ANY" */ 


Linux Example: 


rm "*".lst /* not "multiplied by" */ 
var.003 = anyvalue 

cat "var.003" /* not a compound symbol */ 
w = any 

ls "/w" /* not "divided by ANY" */ 


Enclosing an entire message instruction in parentheses causes the message result to be used as a 
command. Any clause that is a message instruction is not treated as a command. Thus, for example, the 
clause 


myfile^linein 


causes the returned line to be assigned to the variable RESULT, not to be used as a command to an 
external environment, while 


(nyfile^linein) 


would submit the return value from the linein method as a command to the external environment. 


1.16. Using Rexx on Windows and Unix 


Rexx programs can call other Rexx programs as external functions or subroutines with the call 
instruction. 


If a program is called with the call instruction, the program runs in the same process as the calling 
program. If you call another program by a Rexx command, the program is executed in a new process and 
therefore does not share .environment, .local, or the Windows/Unix shell environment. 


Examples: 

call "other.REX" /* runs in the same process */ 

"rexx other.REX" /* runs in a new child process */ 
"start rexx other.REX" /* runs in a new detached process */ 


When Rexx programs call other Rexx programs as commands, the return code of the command is the exit 
value of the called program provided that this value is a whole number in the range -32768 to 32767. 
Otherwise, the exit value is ignored and the called program is given a return code of 0. 
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A keyword instruction is one or more clauses, the first of which starts with a keyword that identifies the 
instruction. Some keyword instructions affect the flow of control, while others provide services to the 
programmer. Some keyword instructions, like DO, can include nested instructions. 


In the syntax diagrams on the following pages, symbols (words) in capitals denote keywords or 
subkeywords. Other words, such as expression, denote a collection of tokens as defined previously. Note, 
however, that the keywords and subkeywords are not case-dependent. The symbols if, If, and iF all 
have the same effect. Note also that you can usually omit most of the clause delimiters (;) shown 
because the end of a line implies them. 


A keyword instruction is recognized only if its keyword is the first token in a clause and if the second 
token does not start with an equal (=) character (implying an assignment) or a colon (implying a label). 
The keywords ELSE, END, OTHERWISE, THEN, and WHEN are treated in the same way. Note that 
any clause that starts with a keyword defined by Rexx cannot be a command. Therefore, 


arg(fred) rest 


is an ARG keyword instruction, not a command that starts with a call to the ARG built-in function. A 
syntax error results if the keywords are not in their correct positions in a DO, IF, or SELECT instruction. 
The keyword THEN is also recognized in the body of an IF or WHEN clause. In other contexts, 
keywords are not reserved and can be used as labels or as the names of variables (though this is generally 
not recommended). 


Subkeywords are reserved within the clauses of individual instructions. For example, the symbols 
VALUE and WITH are subkeywords in the ADDRESS and PARSE instructions, respectively. For 
details, see the description of each instruction. 


Whitespace characters (blanks or horizontal tabs) adjacent to keywords separate the keyword from the 
subsequent token. One or more whitespace characters following VALUE are required to separate the 
expression from the subkeyword in the example following: 


ADDRESS VALUE expression 


However, no whitespace character is required after the VALUE subkeyword in the following example, 
although it would improve readability: 


ADDRESS VALUE"ENVIR" | |number 


2.1. ADDRESS 


»»-ADDRESS--4----------------------------- а a я >< 
*-environment--4------------ +-+ 
| +-expression-+ | 
#4 =SSss> %--ехргеввіоп1------ + 
+-VALUE-+ 
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ADDRESS temporarily or permanently changes the destination of commands. Commands are strings 
sent to an external environment. You can send commands by specifying clauses consisting of only an 
expression or by using the ADDRESS instruction. (See Commands to External Environments.) 


To send a single command to a specified environment, code an environment, a literal string or a single 
symbol, which is taken to be a constant, followed by an expression. The environment name is the name 
of an external procedure or process that can process commands. The expression is evaluated to produce a 
character string value, and this string is routed to the environment to be processed as a command. After 
execution of the command, environment is set back to its original state, thus temporarily changing the 
destination for a single command. The special variable RC and the environment symbol .RS are set and 
errors and failures in commands processed in this way are trapped or traced. 


Windows Example: 

ADDRESS CMD "DIR C:\CONFIG.SYS" 
Linux Example: 

ADDRESS "bash" "15 /usr/lib" 


If you specify only environment, a lasting change of destination occurs: all commands (see Commands) 
that follow are routed to the specified command environment, until the next ADDRESS instruction is 
processed. The previously selected environment is saved. 


Examples: 


Assume that the environment for a Windows text editor is registered by the name EDIT: 


address CMD 

"DIR С: NAUTOEXEC . BAT" 

if rc-0 then "COPY C:\AUTOEXEC.BAT C:\*.TMP" 
address EDIT 


Subsequent commands are passed to the editor until the next ADDRESS instruction. 


Similarly, you can use the VALUE form to make a lasting change to the environment. Here expression], 
which can be a variable name, is evaluated, and the resulting character string value forms the name of the 
environment. You can omit the subkeyword VALUE if expression! does not begin with a literal string or 
symbol, that is, if it starts with a special character such as an operator character or parenthesis. 


Example: 


ADDRESS ("ENVIR"||number) /* Same as ADDRESS VALUE "ENVIR"||number */ 


With no arguments, commands are routed back to the environment that was selected before the previous 
change of the environment, and the current environment name is saved. After changing the environment, 
repeated execution of ADDRESS alone, therefore, switches the command destination between two 

environments. Using a null string for the environment name ("") is the same as using the default 


environment. 


The two environment names are automatically saved across internal and external subroutine and function 
calls. See the CALL instruction (CALL) for more details. 


40 ooRexx Reference Version 4.0.0 


Chapter 2. Keyword Instructions 


The address setting is the currently selected environment name. You can retrieve the current address 
setting by using the ADDRESS built-in function. (See ADDRESS.) The Open Object Rexx: 
Programming Guide describes the creation of alternative subcommand environments. 


2.2. ARG 


>>-ARG--+--------------- %--;----------------------------------- >< 
+-template_list-+ 


ARG retrieves the argument strings provided to a program, internal routine, or method and assigns them 
to variables. It is a short form of the instruction: 


>>-PARSE UPPER ARG--4--------------- %--;----------------------- >< 
+-template_list-+ 


The template_list can be a single template or list of templates separated by commas. Each template 
consists of one or more symbols separated by whitespace characters, patterns, or both. 


The objects passed to the program, routine, or method are converted to string values and parsed into 
variables according to the rules described in Parsing. 


The language processor converts the objects to strings and translates the strings to uppercase (that is, 
lowercase a-z to uppercase A-Z) before processing them. Use the PARSE ARG instruction if you do not 
want uppercase translation. 


You can use the ARG and PARSE ARG instructions repeatedly on the same source objects (typically 
with different templates). The source objects do not change. 


Example: 


/* String passed is "Easy Rider" ж/ 
Arg adjective noun . 


/* Now: ADJECTIVE contains "EASY" ж/ 
/ж NOUN contains "RIDER" ж/ 


If you expect more than one object to be available to the program or routine, you can use a comma іп 
the parsing template 1151 so each template is selected in turn. 


Example: 


/* Function is called by FRED("data X",1,5) */ 
Fred: Arg string, numi, num2 


/* Now: STRING contains "DATA X" ж/ 
/ж NUM1 contains "1" ж/ 
/ж NUM2 contains "5" ж/ 
Notes: 


1. The ARG built-in function can also retrieve or check the arguments. See ARG (Argument). 
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2. The USE ARG instruction (see USE) is an alternative way of retrieving arguments. USE ARG 
performs a direct, one-to-one assignment of argument objects to Rexx variables. You should use this 
when your program needs a direct reference to the argument object, without string conversion or 
parsing. ARG and PARSE ARG produce string values from the argument objects, and the language 
processor then parses the string values. 


2.3. CALL 


%-,-------------- + 
V | 
>>-CALL--+-+-name- -4----4------------ Қ дене hl eue m cies oe a +--;--> 
| +-(expr)-+ +-expression-+ 
+-OFF--+-ANY----------------- %-------------------- + 
| *-ERRÜR--------------- * | 
| *-FAILURE------------- * | 
| *-HALT---------------- * | 
| +-NOTREADY------------ + | 
| +-USER--usercondition-+ | 
%-0М--%-АМҮ----------------- %--%---------------- +-+ 
*t-ERROÜR--------------- + +-NAME--trapname-+ 
*-FAILURE------------- * 
*-HALT---------------- * 
*-NOTREADY------------ * 


+-USER--usercondition-+ 
CALL calls a routine (if you specify name) or controls the trapping of certain conditions (if you specify 
ON or OFF). 


To control trapping, you specify OFF or ON and the condition you want to trap. OFF turns off the 
specified condition trap. ON turns on the specified condition trap. All information on condition traps is 
contained in Conditions and Condition Traps. 


To call a routine, specify name, which must be a literal string or symbol that is taken as a constant. The 
usercondition is a single symbol that is taken as a constant. The trapname is a symbol or string taken as a 
constant. The routine called can be: 


An internal routine 
A subroutine that is in the same program as the CALL instruction or function call that calls it. 
Internal routines are located using label instructions. 

A built-in routine 


A function that is defined as part of the Rexx language. 


An external routine 


A subroutine that is neither built-in nor a label within the same same program as the CALL 
instruction call that invokes it. See Search Order for details on the different types of external 
routines. 
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If name is a literal string (that is, specified in in quotation marks), the search for internal routines is 
bypassed, and only a built-in function or an external routine is called. Note that built-in function names 
are in uppercase. Therefore, a literal string call to a built-in function must also use uppercase characters. 


You can also specify (expr), any valid expression enclosed in parentheses. The expression is evaluated 
before any of the argument expressions, and the value is the target of the CALL instruction. The 

language processor does not translate the expression value into uppercase, so the evaluated name must 
exactly match any label name or built-in function name. (See Labels for a description of label names.) 


The called routine can optionally return a result. In this case, the CALL instruction is functionally 
identical with the clause: 


»»-result-name(----4------------ %-%--)--;---------------------- >< 
+-expression-+ 


You can use any number of expressions, separated by commas. The expressions are evaluated from left 
to right and form the arguments during execution of the routine. Any ARG, PARSE ARG, or USE ARG 
instruction or ARG built-in function in the called routine accesses these objects while the called routine 
is running. You can omit expressions, if appropriate, by including extra commas. 


The CALL then branches to the routine called name, using exactly the same mechanism as function 
calls. See Functions. The search order is as follows: 


Internal routines 


These are sequences of instructions inside the same program, starting at the label that matches name 
in the CALL instruction. If you specify the routine name in quotation marks, then an internal 
routine is not considered for that search order. The RETURN instruction completes the execution of 
an internal routine. 


Built-in routines 


These are routines built into the language processor for providing various functions. They always 
return an object that is the result of the routine. (See ARG (Argument).) 


Note: You can call any built-in function as a subroutine. Any result is stored in RESULT. Simply 
specify CALL, the function name (with no parenthesis) and any arguments: 


call length "string" /ж Same as length("string") */ 
say result /* Produces: 6 ж/ 


External routines 


Users can write or use routines that are external to the language processor and the calling program. 
You can code an external routine in Rexx or in any language that supports the system-dependent 
interfaces. If the CALL instruction calls an external routine written in Rexx as a subroutine, you can 
retrieve any argument strings with the ARG, PARSE ARG, or USE ARG instructions or the ARG 
built-in function. 


For more information on the search order, see Search Order. 
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During execution of an internal routine, all variables previously known are generally accessible. 
However, the PROCEDURE instruction can set up a local variables environment to protect the 
subroutine and caller from each other. The EXPOSE option on the PROCEDURE instruction can expose 
selected variables to a routine. 


Calling an external program or routine defined with a :: ROUTINE directive is similar to calling an 
internal routine. The external routine, however, is an implicit PROCEDURE in that all the caller’s 
variables are always hidden. The status of internal values, for example NUMERIC settings, start with 
their defaults (rather than inheriting those of the caller). In addition, you can use EXIT to return from the 
routine. 


When control reaches an internal routine, the line number of the CALL instruction is available in the 
variable SIGL (in the caller’s variable environment). This can be used as a debug aid because it is 
possible to find out how control reached a routine. Note that if the internal routine uses the 
PROCEDURE instruction, it needs to EXPOSE SIGL to get access to the line number of ће CALL. 


After the subroutine processed the RETURN instruction, control returns to the clause following the 
original CALL. If the RETURN instruction specified an expression, the variable RESULT 15 set to the 
value of that expression. Otherwise, the variable RESULT is dropped (becomes uninitialized). 


An internal routine can include calls to other internal routines, as well as recursive calls to itself. 


Example: 

/* Recursive subroutine execution... */ 

arg z 

call factorial z 

say 2"! =" result 

exit 

factorial: procedure /* Calculate factorial by ж/ 
arg n /* recursive invocation. ж/ 


if n-0 then return 1 
call factorial n-1 
return result * n 


During internal subroutine (and function) execution, all important pieces of information are 
automatically saved and then restored upon return from the routine. These are: 


* The status of loops and other structures: Executing a SIGNAL within a subroutine is safe because 
loops and other structures that were active when the subroutine was called are not ended. However, 
those currently active within the subroutine are ended. 


* Trace action: After a subroutine is debugged, you can insert a TRACE Off at the beginning of it 
without affecting the tracing of the caller. If you want to debug a subroutine, you can insert a TRACE 
Results at the start and tracing is automatically restored to the conditions at entry (for example, Off) 
upon return. Similarly, ? (interactive debug) is saved across routines. 


* NUMERIC settings: The DIGITS, FUZZ, and FORM of arithmetic operations (in NUMERIC) are 
saved and then restored on return. A subroutine can, therefore, set the precision, for example, that it 
needs to use without affecting the caller. 


* ADDRESS settings: The current and previous destinations for commands (see ADDRESS) are saved 
and then restored on return. 


44 ooRexx Reference Version 4.0.0 


Chapter 2. Keyword Instructions 


Condition traps: CALL ON and SIGNAL ON are saved and then restored on return. This means that 
CALL ON, CALL OFF, SIGNAL ON, and SIGNAL OFF can be used in a subroutine without 
affecting the conditions the caller set up. 


* Condition information: This information describes the state and origin of the current trapped 
condition. The CONDITION built-in function returns this information. See CONDITION. 


* „RS value: The value of the .RS environment symbol. (See .RS.) 


* Elapsed-time clocks: A subroutine inherits the elapsed-time clock from its caller (see TIME), but 
because the time clock is saved across routine calls, a subroutine or internal function can 
independently restart and use the clock without affecting its caller. For the same reason, a clock started 
within an internal routine is not available to the caller. 


2.4. DO 


>>-00---+------------- %--%--------------- %--%----------------- %--;-- > 


E 


+-LABEL--name-+ +-| repetitor |-+ +-| conditional |-+ 


>--%--------------------- *--END--4-------- %--;--------------------- >< 
| %----------------- + | +--name--+ 
ІХ | | 
+---instruction-—-;--+-+ 

repetitor: 

| --*-controli-expri--4----------- %--%----------- %--%------------ +-+-- | 
| +-Т0--ехргъ-+ +-BY--exprb-+ +-FOR--exprf-+ | 
*-control2--ÜVER--collection----------------------------------- * 
+-FOREVER------------------------------------------------------ + 
*-exprr-------------------------------------------------------- * 

conditional: 


| --*à-WHILE--exprw-4--------------------------------------------- 
+-UNTIL--expru-+ 


DO groups instructions and optionally processes them repetitively. During repetitive execution, a control 
variable (controll or control2) can be stepped through some range of values. 


Notes: 


1. The LABEL phrase, if used, must precede any repetitor or conditional. 


2. The exprr, expri, exprb, exprt, and exprf options, if present, are any expressions that evaluate to a 
number. The exprr and exprf options are further restricted to result in a positive whole number or 
zero. If necessary, the numbers are rounded according to the setting of NUMERIC DIGITS. 


3. The exprw or expru options, if present, can be any expression that evaluates to 1 or 0. This includes 
the list form of conditional expression supported by IF and WHEN, which is a list of expressions 
separated by ",". Each subexpression must evaluate to either 0 or 1. The list of expressions is 
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evaluated left-to-right. Evaluation will stop with the first 0 result and 0 will be returned as the 
condition result. If all of the subexpressions evaluate to 1, then the condition result is also 1. 


4. The TO, BY, and FOR phrases can be in any order, if used, and are evaluated in the order in which 
they are written. 


5. The instruction can be any instruction, including assignments, commands, message instructions, and 
keyword instructions (including any of the more complex constructs such as IF, SELECT, and the 
DO instruction itself). 


6. The subkeywords WHILE and UNTIL are reserved within a DO instruction in that they cannot be 
used as symbols in any of the expressions. Similarly, TO, BY, and FOR cannot be used in expri, 
exprt, exprb, or exprf. FOREVER is also reserved, but only if it immediately follows the keyword 
DO and is not followed by an equal sign. 


7. The exprb option defaults to 1, if relevant. 


8. The collection can be any expression that evaluates to an object that supports a MAKEARRAY 
method. Array and List items return an array with the items in the appropriate order, as do Streams. 
Tables, Stems, Directories, etc. are not ordered so the items get placed in the array in no particular 
order. 


For more information, refer to Using DO and LOOP. 


2.5. DROP 


>>-DROP----+-name---+-+-- ; ------------------------------------- >< 
*- (name) -+ 


DROP "unassigns" variables, that is, restores them to their original uninitialized state. If name is not 
enclosed in parentheses, it identifies a variable you want to drop and must be a symbol that is a valid 
variable name, separated from any other name by one or more whitespace characters or comments. 


If parentheses enclose a single name, then its value is used as a subsidiary list of variables to drop. 
Whitespace characters are not necessary inside or outside the parentheses, but you can add them if 
desired. This subsidiary list must follow the same rules as the original list, that is, be valid character 
strings separated by whitespace, except that no parentheses are allowed. The list need not contain any 
names—that is, it can be empty. 


Variables are dropped from left to right. It is not an error to specify a name more than once or to drop a 
variable that is not known. If an exposed variable is named (see EXPOSE and PROCEDURE), then the 
original variable is dropped. 


Example: 

ј=4 

Drop а 2.3 z.j 

/* Drops the variables: А, 2.3, and 2.4 ж/ 
/* so that reference to them returns their names. ж/ 


Неге, a variable name in parentheses is used as а subsidiary list. 
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Example: 


mylist-"c d e" 

drop (mylist) f 

/* Drops the variables C, D, E, and F */ 
/* Does not drop MYLIST ж/ 


Specifying a stem (that is, а symbol that contains only one period as the last character) assigns the stem 
variable to a new, empty stem object. 


Example: 


Drop z. 
/* Assigns stem variable z. to a new empty stem object */ 


2.6. EXIT 


>>-EXIT--+------------ %--;------------------------------------- >< 
+-expression-+ 


EXIT leaves a program unconditionally. Optionally, EXIT returns a result object to the caller. The 
program is stopped immediately, even if an internal routine is being run. If no internal routine is active, 
RETURN (see RETURN) and EXIT are identical in their effect on the program running. 


If you specify expression, it is evaluated and the object resulting from the evaluation is passed back to the 
caller when the program stops. 


Example: 


153 
Exit j+*4 
/* Would exit with the string "12" */ 


If you do not specify expression, no data is passed back to the caller. If the program was called as a 
function, this is detected as an error. 


You can also use EXIT within a method. The method is stopped immediately, and the result object, if 
specified, is returned to the sender. If the method has previously issued a REPLY instruction (see 
REPLY), the EXIT instruction must not include a result expression. 


Notes: 


1. If the program was called through a command interface, an attempt is made to convert the returned 
value to a return code acceptable by the underlying operating system. The returned string must be a 
whole number whose value fits in a 16-bit signed integer (within the range -(2**15) to (2**15-1). If 
the conversion fails, no error is raised, and a return code of 0 is returned. 


2. If you do not specify EXIT, EXIT is implied at the end of the program, but no result value is 
returned. 


3. On Unix/Linux systems the returned value is limited to a numerical value between 0 and 255 (an 
unsigned byte). 
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2.7. EXPOSE 


>>-EXPOSE----+-name---+-+-- ; ----------------------------------- >< 
+- (name) -* 


EXPOSE causes the object variables identified in name to be exposed to a method. References to 
exposed variables, including assigning and dropping, access variables in the current object's variable 
pool. (An object variable pool is a collection of variables that is associated with an object rather than 
with any individual method.) Therefore, the values of existing variables are accessible, and any changes 
are persistent even after RETURN or EXIT from the method. 


Any changes a method makes to an object variable pool are immediately visible to any other methods 
that share the same object variable scope. All other variables that a method uses are local to the method 
and are dropped on RETURN or EXIT. If an EXPOSE instruction is included, it must be the first 
instruction of the method. 


If parentheses enclose a single name, then, after the variable name is exposed, the character string value 
of name is immediately used as a subsidiary list of variables. Whitespace characters are not necessary 
inside or outside the parentheses, but you can add them if desired. This subsidiary list must follow the 
same rules as the original list, that is, valid variable names separated by whitespace characters, except 
that no parentheses are allowed. 


Variables are exposed in sequence from left to right. It is not an error to specify a name more than once, 
or to specify a name that has not been used as a variable. 


Example: 


/* Example of exposing object variables */ 


myobj = .myclass^new 
myobj^c 
myobj^d /* Would display "Z is: 120" ж/ 
::class myclass /ж Тһе ::CLASS directive ж/ 
/* (see ::CLASS) ж/ 
::method с /* Тһе ::METHOD directive ж/ 
/* (see ::METHOD) ж/ 
ехрове 2 
z = 100 /* Would assign 100 to the object variable z */ 
return 
::method а 
expose z 
z-z*20 /* Would add 20 to the same object variable z */ 


say "Z іѕ:" 2 
return 


You can expose an entire collection of compound variables (see Compound Symbols) by specifying their 
stem in the variable list or a subsidiary list. The variables are exposed for all operations. 


Example: 


expose j k c. d. 
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/* This exposes "J", "K", and all variables whose */ 
/* name starts with "C." or "D." */ 
c.1="7." /* This sets "C.1" in the object ж/ 
/* variable pool, even if it did not */ 
/* previously exist. ж/ 


2.8. FORWARD 


»»-FORWARD--4---------- +--+------------------------ +------------ > 
+-CONTINUE-+ +-ARGUMENTS--expra------- + 
| 4255555 + | 
| ү | | 
+-АВВАУ--(----ехрг1-+--) -+ 


>--+---------------- +--+-------------- +--+----------- %--------- >< 
T-MESSAGE--exprm-* +-CLASS--exprs-+ +-TO--exprt-+ 


Note: You can specify the options in any order. 


FORWARD forwards the message that caused the currently active method to begin running. The 
FORWARD instruction can change parts of the forwarded message, such as the target object, the 
message name, the arguments, and the superclass override. 


If you specify the TO option, the language processor evaluates exprt to produce a new target object for 
the forwarded message. The exprt is a literal string, constant symbol, or expression enclosed in 
parentheses. If you do not specify the TO option, the initial value of the Rexx special variable SELF is 
used. 


If you specify the ARGUMENTS option, the language processor evaluates expra to produce an array 
object that supplies the set of arguments for the forwarded message. The expra can be a literal string, 
constant symbol, or expression enclosed in parentheses. The ARGUMENTS value must evaluate to a 
Rexx array object. 


If you specify the ARRAY option, each expri is an expression (use commas to separate the expressions). 
The language processor evaluates the expression list to produce a set of arguments for the forwarded 
message. It is an error to use both the ARRAY and the ARGUMENTS options on the same FORWARD 
instruction. 


If you specify neither ARGUMENTS nor ARRAY, the language processor uses the same arguments 
specified on the original method call. 


If you specify the MESSAGE option, the exprm is a literal string, a constant symbol, or an expression 
enclosed in parentheses. If you specify an expression enclosed in parentheses, the language processor 
evaluates the expression to obtain its value. The uppercase character string value of the MESSAGE 
option is the name of the message that the FORWARD instruction issues. 


If you do not specify MESSAGE, FORWARD uses the message name used to call the currently active 
method. 
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If you specify the CLASS option, the exprs is a literal string, a constant symbol, or an expression 
enclosed in parentheses. This is the class object used as a superclass specifier on the forwarded message. 


If you do not specify CLASS, the message is forwarded without a superclass override. 


If you do not specify the CONTINUE option, the language processor immediately exits the current 
method before forwarding the message. Results returned from the forwarded message are the return 
value from the original message that called the active method (the caller of the method that issued the 
FORWARD instruction). Any conditions the forwarded message raises are raised in the calling program 
(without raising a condition in the method issuing the FORWARD instruction). 


If you specify the CONTINUE option, the current method does not exit and continues with the next 
instruction when the forwarded message completes. If the forwarded message returns a result, the 
language processor assigns it to the special variable RESULT. If the message does not return a result, the 
language processor drops (uninitializes) the variable RESULT. 


The FORWARD instruction passes all or part of an existing message invocation to another method. For 
example, the FORWARD instruction can forward a message to a different target object, using the same 
message name and arguments. 


Example: 


::method substr 
forward to (self~string) /* Forward to the string value */ 


You can use FORWARD in an UNKNOWN method to reissue to another object the message that the 
UNKNOWN method traps. 


Example: 


::method unknown 
use arg msg, args 
/* Forward to the string value */ 
/* passing along the arguments */ 
forward to (self~string) message (msg) arguments (args) 


You can use FORWARD in a method to forward a message to a superclass’s methods, passing the same 
arguments. This is very common usage in object INIT methods. 


Example: 


::class savings subclass account 

::method init 
expose type penalty 
forward class (super) continue /* Send to the superclass ж/ 
type = "Savings" /* Now complete initialization */ 
penalty = "1% for balance under 500" 


In the preceding example, the CONTINUE option causes the FORWARD message to continue with the 
next instruction, rather than exiting the Savings class INIT method. 
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2.9. GUARD 


>>-GUARD--+-ON--+------------------ %--%--;--------------------- >< 
| +-WHEN--expression-+ | 
*-ÜFF--4------------------ +-+ 
+-WHEN--expression-+ 


GUARD controls a method’s exclusive access to an object. 


GUARD ON acquires for an active method exclusive use of its object variable pool. This prevents other 
methods that also require exclusive use of the same variable pool from running on the same object. If 
another method has already acquired exclusive access, the GUARD instruction causes the issuing 
method to wait until the variable pool is available. 


GUARD OFF releases exclusive use of the object variable pool. Other methods that require exclusive use 
of the same variable pool can begin running. 


If you specify WHEN, the method delays running until the expression evaluates to 1 (true). If the 
expression evaluates to 0 (false), GUARD waits until another method assigns or drops an object variable 
(that is, a variable named on an EXPOSE instruction) used in the WHEN expression. When an object 
variable changes, GUARD reevaluates the WHEN expression. If the expression evaluates to true, the 
method resumes running. If the expression evaluates to false, GUARD resumes waiting. 


Example: 


::method c 
expose y 
if у>0 then 
return 1 
else 
return 0 
::method а 
expose 2 
guard on when z>0 
self~c /* Reevaluated when Z changes ж/ 
say "Method D" 


If you specify WHEN and the method has exclusive access to the object's variable pool, then the 
exclusive access is released while GUARD is waiting for an object variable to change. Exclusive access 
is reacquired before the WHEN expression is evaluated. Once the WHEN expression evaluates to 1 
(true), exclusive access is either retained (for GUARD ON WHEN) or released (for GUARD OFF 
WHEN), and the method resumes running. 


Note: If the condition expression cannot be met, GUARD ON WHEN puts the program in a 
continuous wait condition. This can occur in particular when several activities run concurrently. See 
Guarded Methods for more information. 
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2.10. IF 


>>-ІЕ--ехргеввіопһ--%---%--ТНЕМ--%---%--іпвігісбіоп-------------- > 
+-;-+ Жез 
>--%-------------------------- %-------------------------------- >< 
+-ELSE--+---+--instruction-+ 
tao 


IF conditionally processes an instruction or group of instructions depending on the evaluation of the 
expression. The expression is evaluated and must result in 0 or 1. 


The instruction after the THEN is processed only if the result is 1 (true). If you specify an ELSE, the 
instruction after ELSE is processed only if the result of the evaluation is 0 (false). 


Example: 


if answer="YES" then say "OK!" 
else say "Why not?" 


Remember that if the ELSE clause is on the same line as the last clause of the THEN part, you need a 
semicolon before ELSE. 


Example: 
if answer="YES" then say "OK!"; else say "Why not?" 


ELSE binds to the nearest IF at the same level. You can use the NOP instruction to eliminate errors and 
possible confusion when IF constructs are nested, as in the following example. 


Example: 


If answer = "YES" Then 
If name = "FRED" Then 
say "OK, Fred." 
Else 
nop 
Else 
say "Why not?" 


The expression may also be a list of expressions separated by ",". Each subexpression must evaluate to 
either 0 or 1. The list of expressions is evaluated left-to-right. Evaluation will stop with the first 0 result 
and 0 will be returned as the condition result. If all of the subexpressions evaluate to 1, then the condition 
result is also 1. 


Example: 

If answer~datatype(’w’), answer//2 = 0 Then 
say answer "is even" 

Else 


say answer "is odd" 


The example above is not the same as using the following 


If answer~datatype(’w’) & answer//2 = 0 Then 
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say answer "is even" 
Else 
say answer "is odd" 


The logical & operator will evaluate both terms of the operation, so the term "answer//2" will result in a 
syntax error if answer is a non-numeric value. With the list conditional form, evaluation will stop with 
the first false result, so the "answer//2" term will not be evaluated if the datatype test returns 0. 


Notes: 


1. The instruction can be any assignment, message instruction, command, or keyword instruction, 
including any of the more complex constructs such as DO, LOOP, SELECT, or the IF instruction 
itself. A null clause is not an instruction, so putting an extra semicolon (or label) after THEN or 
ELSE is not equivalent to putting a dummy instruction (as it would be in C). The NOP instruction is 
provided for this purpose. 


2. The symbol THEN cannot be used within expression, because the keyword THEN is treated 
differently in that it need not start a clause. This allows the expression on the IF clause to be ended 
by THEN, without a semicolon (;) being required. 


2.11. INTERPRET 


>2-1ТЕВРВЕТ--ехргевтлоп---------------------+-<+-<---- >< 


INTERPRET processes instructions that have been built dynamically by evaluating expression. 


The expression is evaluated to produce a character string, and is then processed (interpreted) just as 
though the resulting string were a line inserted into the program and bracketed by a DO; and ап ЕХО). 


Any instructions (including INTERPRET instructions) are allowed, but note that constructions such as 
DO...END and SELECT...END must be complete. For example, a string of instructions being interpreted 
cannot contain a LEAVE or ITERATE instruction (valid only within a repetitive loop) unless it also 
contains the whole repetitive DO...END or LOOP...END construct. 


A semicolon is implied at the end of the expression during execution, if one was not supplied. 


Examples: 


/* INTERPRET example */ 


data="FRED" 

interpret data "= 4" 

/* Builds the string "FRED = 4" and ж/ 
/ж Processes: FRED = 4; */ 
/* Thus the variable FRED is set to "4" ж/ 


/ж Another INTERPRET example */ 
data="do 3; say "Hello there!"; end" 


interpret data /* Displays: ж/ 
/* Hello there! ж/ 
/* Hello there! ж/ 
/* Hello there! ж/ 
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Notes: 


1. Labels within the interpreted string are not permanent and are, therefore, an error. 


2. Executing the INTERPRET instruction with TRACE R or TRACE I can be helpful in interpreting the 
results you get. 


Example: 


/* Here is a small Rexx program. */ 
Trace Int 

name="Kitty" 

indirect="name" 

interpret 'say "Hello"' indirect'"!"' 


When this is run, you get the following trace: 


3 *-* name-"Kitty" 
>L> "Kitty" 
>>> "Kitty" 
4 ж-ж indirect="name" 
>L> "name" 
>>> "name" 
Б ж-ж interpret ’say "Hello"’ indirect’"!"’ 
>L> "say "Hello"" 
>V> | INDIRECT => "name" 


>0> " "=> "say "Hello" name" 
>L> пи 1 пи 

>0> пи > "вау "Hello" name" ! we 
>>> "say "Hello" name"!"" 


5 *-* say "Hello" name"!" 
>L> "Hello" 
>V> NAME => "Kitty" 


>0> "И => "Hello Kitty" 
>L> при 
»0»  "" => "Hello Kitty!" 


>>> "Hello Kitty!" 
Hello Kitty! 


Lines 3 and 4 set the variables used in line 5. Execution of line 5 then proceeds in two stages. First 
the string to be interpreted is built up, using a literal string, a variable (INDIRECT), and another literal 
string. The resulting pure character string is then interpreted, just as though it were actually part of 
the original program. Because it is a new clause, it is traced as such (the second ж-ж trace flag under 
line 5) and is then processed. Again a literal string is concatenated to the value of a variable (NAME) 
and another literal, and the final result (Hello Kitty!)is then displayed. 


3. For many purposes, you can use the VALUE function (see VALUE) instead of the INTERPRET 
instruction. The following line could, therefore, have replaced line 5 in the previous example: 


say "Hello" value(indirect)"!" 


INTERPRET is usually required only in special cases, such as when two or more statements are to 
be interpreted together, or when an expression is to be evaluated dynamically. 


4. You cannot use a directive (see Directives) within an INTERPRET instruction. 
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2.12. ITERATE 


>>-ІТЕВАТЕ--%------ %--;---------------------------------------- >< 
+-name-+ 


ITERATE alters the flow within a repetitive loop (that is, any DO construct other than that with a simple 
DO or a LOOP instruction). 


Execution of the group of instructions stops, and control is passed to the DO or LOOP instruction just as 
though the END clause had been encountered. The control variable, if any, is incremented and tested, as 
usual, and the group of instructions is processed again, unless the DO or LOOP instruction ends the loop. 


The name is a symbol, taken as a constant. If name is not specified, ITERATE continues with the current 
repetitive loop. If name is specified, it must be the name of the control variable or the LABEL name of a 
currently active loop, which can be the innermost, and this is the loop that is stepped. Any active loops 
inside the one selected for iteration are ended (as though by a LEAVE instruction). 


Example: 


loop label MyLabelName i=1 to 4 /* label set to ’MYLABELNAME’ ж/ 
if i=2 then iterate 
say i 

end myLabelName 

/* Displays the numbers: 
1 


4 
ж/ 


Notes: 


1. If specified, name must match the symbol naming the control variable or LABEL name in the DO or 
LOOP clause in all respects except the case. No substitution for compound variables is carried out 
when the comparison is made. 


2. A loop is active if it is currently being processed. If a subroutine is called, or an INTERPRET 
instruction is processed, during the execution of a loop, the loop becomes inactive until the 
subroutine has returned or the INTERPRET instruction has completed. ITERATE cannot be used to 
continue with an inactive loop. 


3. If more than one active loop uses the same name, ITERATE selects the innermost loop. 


2.13. LEAVE 


»»-LEAVE--4------ %--;------------------------------------------ >< 
+-паше-+ 


LEAVE causes an immediate exit from one or more repetitive loops or block instruction (simple DO or 
SELECT). 


Processing of the group of instructions is ended, and control is passed to the instruction following the 
END clause, just as though the END clause had been encountered and the termination condition had 
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been met. However, on exit, the control variable, if any, contains the value it had when the LEAVE 
instruction was processed. 


The name is a symbol, taken as a constant. If name is not specified, LEAVE ends the innermost active 
repetitive loop. If name is specified, it must be the name of the control variable or LABEL name of a 
currently active LOOP, DO, or SELECT, which can be the innermost, and that block, and any active 
block inside it, are then ended. Control then passes to the clause following the END that matches the 
instruction of the selected block. 


Example: 


max=5 
do label myDoBlock /* define a label *MYDOBLOCK’ */ 
loop i=1 to max /* label defaults to control variable ’I’ */ 
if i = 2 then iterate i 
if i = 4 the leave myDoBlock 
say i 
end i 
say ’after looping’ max ’times’ 
end myDoBlock 
/* Displays the following 
1 
3 
after looping 4 times 


*/ 


Notes: 


1. If specified, name must match the symbol naming the control variable or LABEL name in the DO, 
LOOP, or SELECT clause in all respects except the case. No substitution for compound variables is 
carried out when the comparison is made. 


2. A loop is active if it is currently being processed. If a subroutine is called, or an INTERPRET 
instruction is processed, during execution of a loop, the loop becomes inactive until the subroutine 
has returned or the INTERPRET instruction has completed. LEAVE cannot be used to end an 
inactive block. 


3. If more than one active block uses the same control variable, LEAVE selects the innermost block. 


2.14. LOOP 


>>-100Р--+------------- %--%--------------- %--%----------------- %--;--> 
+-LABEL--name-+ +-| repetitor |-% +-| conditional |-+ 


>--%-------------------- +--END--+-------- %--;----------------------- >< 
| %---------------- + | +--name--+ 
|v | | 
+---instruction--;-+-+ 

repetitor: 

| --*-controli-expri--4----------- %--%----------- +--+------------ +-+-- | 
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| +-TO--exprt-+ +-BY--exprb-+ +-FOR--exprf-+ | 


*-control2--ÜVER--collection------------------------------ ee + 

%-ЕОВЕУЕН------------------------------------------------------ % 

%-ехргг-------------------------------------------------------- % 
conditional: 


| --*à-WHILE--exprw-4--------------------------------------------- 
+-UNTIL--expru-+ 


LOOP groups instructions and processes them repetitively. During repetitive execution, a control 
variable (controll or control2) can be stepped through some range of values. 


Notes: 


1. The LABEL phrase, if used, must precede any repetitor or conditional. 


2. The exprr, expri, exprb, exprt, and exprf options, if present, are any expressions that evaluate to a 
number. The exprr and exprf options are further restricted to result in a positive whole number or 
zero. If necessary, the numbers are rounded according to the setting of NUMERIC DIGITS. 


3. The exprw or expru options, if present, can be any expression that evaluates to 1 or 0. This includes 
the list form of conditional expression supported by IF and WHEN, which is a list of expressions 
separated by ",". Each subexpression must evaluate to either 0 or 1. The list of expressions is 
evaluated left-to-right. Evaluation will stop with the first 0 result and 0 will be returned as the 


condition result. If all of the subexpressions evaluate to 1, then the condition result is also 1. 


4. The TO, BY, and FOR phrases can be in any order, if used, and are evaluated in the order in which 
they are written. 


5. The instruction can be any instruction, including assignments, commands, message instructions, and 
keyword instructions (including any of the more complex constructs such as IF, SELECT, and the 
LOOP instruction itself). 


6. The subkeywords WHILE and UNTIL are reserved within a LOOP instruction in that they cannot be 
used as symbols in any of the expressions. Similarly, TO, BY, and FOR cannot be used in expri, 
exprt, exprb, or exprf. FOREVER is also reserved, but only if it immediately follows the keyword 
LOOP and is not followed by an equal sign. 


7. The exprb option defaults to 1, if relevant. 


8. The collection can be any expression that evaluates to an object that supports a MAKEARRAY 
method. Array and List items return an array with the items in the appropriate order, as do Streams. 
Tables, Stems, Directories, etc. are not ordered so the items get placed in the array in no particular 
order. 


For more information, refer to Using DO and LOOP. 


2.15. NOP 


NOP is a dummy instruction that has no effect. It can be useful as the target of a THEN or ELSE clause. 
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Example: 

Select 
when a=c then nop /* Do nothing */ 
when a>c then say "A > C" 
otherwise say "A < C" 

end 


Note: Putting an extra semicolon instead of the NOP would merely insert a null clause, which would 
be ignored. The second WHEN clause would be seen as the first instruction expected after the 
THEN, and would, therefore, be treated as a syntax error. NOP is a true instruction, however, and is, 
therefore, a valid target for the THEN clause. 


2.16. NUMERIC 


>>-NUMERIC--+-DIGITS--+------------- %---------- %--;------------ >< 
| +-ехргеѕѕіопі-+ | 
| *-SCIENTIFIC------------- + | 
*-FÜRM--4------------------------ +-+ 
| +-ENGINEERING------------ + | 
| %-%------- +--ехргеѕѕіоп2-+ | 
| +-VALUE-+ | 
*-FUZZ--4------------- %------------ + 


+-expression3-+ 


NUMERIC changes the way in which a program carries out arithmetic operations. The options of this 
instruction are described in detail in Numbers and Arithmetic. 


NUMERIC DIGITS 


controls the precision to which arithmetic operations and built-in functions are evaluated. If you 
omit expressionl, the precision defaults to 9 digits, but can be overridden on a source-file basis 
using the ::OPTIONS directive. Otherwise, the character string value result of expression] must 
evaluate to a positive whole number and must be larger than the current NUMERIC FUZZ setting. 


There is no limit to the value for DIGITS (except the amount of storage available), but high 
precisions are likely to require a great amount of processing time. It is recommended that you use 
the default value whenever possible. 


You can retrieve the current NUMERIC DIGITS setting with the DIGITS built-in function. See 
DIGITS. 


NUMERIC FORM 


controls the form of exponential notation for the result of arithmetic operations and built-in 
functions. This can be either SCIENTIFIC (in which case only one, nonzero digit appears before the 
decimal point) or ENGINEERING (in which case the power of 10 is always a multiple of 3). The 
default is SCIENTIFIC. The subkeywords SCIENTIFIC or ENGINEERING set the FORM directly, 
or it is taken from the character string result of evaluating the expression (expression2) that follows 
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VALUE. The result in this case must be either SCIENTIFIC or ENGINEERING. You can omit the 
subkeyword VALUE if expression2 does not begin with a symbol or a literal string, that is, if it 
starts with a special character, such as an operator character or parenthesis. 


You can retrieve the current NUMERIC FORM setting with the FORM built-in function. See 
FORM. 


NUMERIC FUZZ 


controls how many digits, at full precision, are ignored during a numeric comparison operation. 
(See Numeric Comparisons.) If you omit expression3, the default is 0 digits. Otherwise, the 
character string value result of expression3 must evaluate to 0 or a positive whole number rounded, 
if necessary, according to the current NUMERIC DIGITS setting, and must be smaller than the 
current NUMERIC DIGITS setting. 


NUMERIC FUZZ temporarily reduces the value of NUMERIC DIGITS by the NUMERIC FUZZ 
value during every numeric comparison. The numbers are subtracted under a precision of DIGITS 
minus FUZZ digits during the comparison and are then compared with 0. 


You can retrieve the current NUMERIC FUZZ setting with the FUZZ built-in function. See FUZZ. 


Note: The three numeric settings are automatically saved across internal subroutine and function 
calls. See the CALL instruction (CALL) for more details. 


2.17. OPTIONS 


>>-OPTIONS--+------------ %--;------------------------------------- >< 
+-expression-+ 
The OPTIONS instruction is used to pass special requests to the language processor. 


The expression is evaluated, and individual words in the result that are meaningful to the language 
processor will be obeyed. Optiions might control how the interpreter optimizes code, enforces standards, 
enables implementation-dependent features, etc.). Unrecognized words in the result are ignored, since 
they are assumed to be instructions for a different language processor. 


Open Object Rexx does not recognize any option keywords. 


2.18. PARSE 


>>-PARSE--+------- +--+---------- %------------------------------- > 
+-UPPER-+ +-CASELESS-+ 
+-LOWER-+ 
>--+-ARG------------------------- %--%--------------- %--;------- >< 
*S-LINEIN---------------------- + +-template_list-+ 
S-PULL--------—--------—------- * 
*-SO0URCE---------------------- * 
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+-VALUE--+------------ +--WITH-+ 
| +-expression-+ | 
+-VAR--name------------------- + 
+-VERSION--------------------- + 


Note: You can specify UPPER and CASELESS or LOWER and CASELESS in either order. 


PARSE assigns data from various sources to one or more variables according to the rules of parsing. (See 
Parsing.) 
If you specify UPPER, the strings to be parsed are translated to uppercase before parsing. If you specify 


LOWER, the strings are translated to lowercase. Otherwise no translation takes place. 


If you specify CASELESS, character string matches during parsing are made independent of the case. 
This means a letter in uppercase is equal to the same letter in lowercase. 


The template list сап be a single template or list of templates separated by commas. Each template 
consists of one or more symbols separated by whitespace, patterns, or both. 


Each template is applied to a single source string. Specifying several templates is not a syntax error, but 
only the PARSE ARG variant can supply more than one non-null source string. See Parsing Several 
Strings for information on parsing several source strings. 


If you do not specify a template, no variables are set but the data is prepared for parsing, if necessary. 
Thus for PARSE PULL, a data string is removed from the current data queue, for PARSE LINEIN (and 
PARSE PULL if the queue is empty), a line is taken from the default input stream, and for PARSE 
VALUE, expression is evaluated. For PARSE VAR, the specified variable is accessed. If it does not have 
a value, the NOVALUE condition is raised, if it is enabled. 


The following list describes the data for each variant of the PARSE instruction. 


PARSE ARG 


parses the strings passed to a program, routine, or method as input arguments. (See the ARG 
instruction in ARG for details and examples.) 


Note: Parsing uses the string values of the argument objects. The USE ARG instruction provides 
direct access to argument objects. You can also retrieve or check the argument objects to a 
Rexx program, routine, or method with the ARG built-in function (see ARG (Argument)). 


PARSE LINEIN 


parses the next line of the default input stream. (See Input and Output Streams for a discussion of 
Rexx input and output.) PARSE LINEIN is a shorter form of the following instruction: 
>>-PARSE VALUE LINEIN() WITH--+--------------- %--;-------------- >< 


+-template_list-+ 


If no line is available, program execution usually pauses until a line is complete. Use PARSE 
LINEIN only when direct access to the character input stream is necessary. Use the PULL or 
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PARSE PULL instructions for the usual line-by-line dialog with the user to maintain generality. 
PARSE LINEIN will not pull lines from the external data queue. 


To check if any lines are available in the default input stream, use the built-in function LINES. See 
LINES (Lines Remaining) and LINEIN (Line Input). 


PARSE PULL 


parses the next string of the external data queue. If the external data queue is empty, PARSE PULL 
reads a line of the default input stream (the user’s terminal), and the program pauses, if necessary, 
until a line is complete. You can add data to the head or tail of the queue by using the PUSH and 
QUEUE instructions, respectively. You can find the number of lines currently in the queue with the 
QUEUED built-in function. (See QUEUED.) The queue remains active as long as the language 
processor is active. Other programs in the system can alter the queue and use it to communicate 
with programs written in Rexx. See also the PULL instruction in PULL. 


Note: PULL and PARSE PULL read the current data queue. If the queue is empty, they read the 
default input stream, .INPUT (typically, the keyboard). 


PARSE SOURCE 


parses data describing the source of the program running. The language processor returns a string 
that does not change while the program is running. 


The source string contains operating system name, followed by either COMMAND, FUNCTION, 
SUBROUTINE, or METHOD, depending on whether the program was called as a host command or from a 
function call in an expression or using the CALL instruction or as a method of an object. These two 
tokens are followed by the complete path specification of the program file. 


The string parsed might, therefore, look like this: 
WindowsNT COMMAND C:\MYDIR\RexxTRY.CMD 
or 


LINUX COMMAND /opt/orexx/bin/rexxtry.cmd 


PARSE VALUE 


parses the data, a character string, that is the result of evaluating expression. If you specify no 
expression, the null string is used. Note that WITH is a subkeyword in this context and cannot be 
used as a symbol within expression. 


Thus, for example: 


PARSE VALUE time() WITH hours ":" mins ":" secs 
gets the current time and splits it into its constituent parts. 


PARSE VAR name 


parses the character string value of the variable name. The name must be a symbol that is valid as a 
variable name, which means it cannot start with a period or a digit. Note that the variable name is 
not changed unless it appears in the template, so that, for example: 


ooRexx Reference Version 4.0.0 61 


Chapter 2. Keyword Instructions 


PARSE VAR string wordi string 


removes the first word from string, puts it in the variable word1, and assigns the remainder back to 
string. 


PARSE UPPER VAR string wordi string 


also translates the data from string to uppercase before it is parsed. 


PARSE VERSION 


parses information describing the language level and the date of the language processor. This 
information consists of five blank-delimited words: 


* The string REXX-ooRexx 
* The language level description, for example 6.03. 


* Three tokens that describe the language processor release date in the same format as the default 
for the DATE built-in function (see DATE), for example, "27 Sep 2007". 


2.19. PROCEDURE 


>>-PROCEDURE--+ 

| 

| V | | 

+-EXPOSE----+-name---+-+-+ 
+-(name)-+ 


PROCEDURE, within an internal routine (subroutine or function), protects the caller’s variables by 
making them unknown to the instructions that follow it. After a RETURN instruction is processed, the 
original variable environment is restored and any variables used in the routine (that were not exposed) 
are dropped. (An exposed variable is one belonging the caller of a routine that the PROCEDURE 
instruction has exposed. When the routine refers to, or alters, the variable, the original (caller's) copy of 
the variable is used.) An internal routine need not include a PROCEDURE instruction. In this case the 
variables it is manipulating are those the caller owns. If the PROCEDURE instruction is used, it must be 
the first instruction processed after the CALL or function invocation; that is, it must be the first 
instruction following the label. 


If you use the EXPOSE option, any variable specified by the name is exposed. Any reference to it 
(including setting and dropping) is made to the variables environment the caller owns. Hence, the values 
of existing variables are accessible, and any changes are persistent even on RETURN from the routine. If 
the name is not enclosed in parentheses, it identifies a variable you want to expose and must be a symbol 
that is a valid variable name, separated from any other name with one or more whitespace characters. 


If parentheses enclose a single name, then, after the variable name is exposed, the character string value 
of name is immediately used as a subsidiary list of variables. Whitespace characters are not necessary 
inside or outside the parentheses, but you can add them if desired. This subsidiary list must follow the 
same rules as the original list, that is, valid variable names separated by whitespace characters, except 
that no parentheses are allowed. 


Variables are exposed from left to right. It is not an error to specify a name more than once, or to specify 
a name that the caller has not used as a variable. 
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Any variables in the main program that are not exposed are still protected. Therefore, some of the caller’s 
variables can be made accessible and can be changed, or new variables can be created. All these changes 
are visible to the caller upon RETURN from the routine. 


Example: 


/* This is the main Rexx program */ 


ігі; z.1-"a" 

call toft 

say j km /* Displays "1 7 M" ж/ 

exit 

/* This is a subroutine */ 

toft: procedure expose j k z.j 
say j kz.j  /* Displays "1 Ка" ж/ 
k=7; m=3 /* Note: M is not exposed ж/ 
return 


Note that if Z.J in the EXPOSE list is placed before J, the caller’s value of J is not visible, so Z.1 is not 
exposed. 


The variables in a subsidiary list are also exposed from left to right. 


Example: 


/* This is the main Rexx program */ 
j=1;k=6;m=9 

a -"j ки" 

call test 

exit 


/* This is a subroutine */ 

test: procedure expose (a)  /* Exposes A, J, K, and M ж/ 
sayajkm /* Displays "j km 1 6 9" ж/ 
return 


You can use subsidiary lists to more easily expose a number of variables at a time or, with the VALUE 
built-in function, to manipulate dynamically named variables. 


Example: 


/* This is the main Rexx program */ 
c=11; d=12; e=13 


Showlist="c d" /* but not E ж/ 
call Playvars 

say cdef /* Displays "11 New 13 9" */ 
exit 

/* This is a subroutine ж/ 


Playvars: procedure expose (showlist) f 
say word(showlist,2) /* Displays "d" ж/ 
say value(word(showlist,2),"New") /* Displays "12" and sets new value */ 


say value(word(showlist,2)) /* Displays "New" ж/ 
е-8 /ж E is not exposed ж/ 
f-9 /* F was explicitly exposed ж/ 
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return 


Specifying a stem as name exposes this stem and all possible compound variables whose names begin 
with that stem. (See .) 


Example: 


/* This is the main Rexx program */ 
a.-11; i-13; j=15 

і=і+1 

С.5 = "FRED" 

call lucky7 

say a. a.1i j c. c.5 

say "You should see 11 7 14 15 C. FRED" 
exit 


lucky7:Procedure Expose i j a. c. 


/* This exposes I, J, and all variables whose ж/ 
/ж names start with А. or С. ж/ 
A.1-"7" /* This sets А.1 in the caller-'s ж/ 
/ж environment, even if it did not ж/ 
/* previously exist. ж/ 
return 


Note: Variables can be exposed through several generations of routines if they are included in all 
intermediate PROCEDURE instructions. 


See the CALL instruction and function descriptions in CALL and Functions for details and examples of 
how routines are called. 


2.20. PULL 


>>-PULL--+--------------- %--;---------------------------------- >< 
+-template_list-+ 


PULL reads a string from the head of the external data queue or, if the external data queue is empty, from 
the standard input stream (typically the keyboard). (See Input and Output Streams for a discussion of 
Rexx input and output.) It is a short form of the following instruction: 


>>-PARSE UPPER PULL--+--------------- %--;---------------------- >< 
+-template_list-+ 


The current head of the queue is read as one string. Without a template_list specified, no further action is 
taken and the string is thus effectively discarded. The template_list can be a single template or list of 
templates separated by commas, but PULL parses only one source string. Each template consists of one 
or more symbols separated by whitespace, patterns, or both. 


If you specify several comma-separated templates, variables in templates other than the first one are 
assigned the null string. The string is translated to uppercase (that is, lowercase a-z to uppercase A-Z) and 
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then parsed into variables according to the rules described in Parsing. Use the PARSE PULL instruction 
if you do not desire uppercase translation. 


Note: If the current data queue is empty, PULL reads from the standard input (typically, the 
keyboard). If there is a PULL from the standard input, the program waits for keyboard input with no 
prompt. 


Example: 


Say "Do you want to erase the file? Answer Yes or No:" 
Pull answer . 
if answer-"NO" then say "The file will not be erased." 


Here the dummy placeholder, a period (.), is used in the template to isolate the first word the user enters. 


If the external data queue is empty, a line is read from the default input stream and the program pauses, if 
necessary, until a line is complete. (This is as though PARSE UPPER LINEIN had been processed. See 
PARSE LINEIN.) 


The QUEUED built-in function (see QUEUED) returns the number of lines currently in the external data 
queue. 


2.21. PUSH 


»»-PUSH--4------------ %--;------------------------------------- >< 
+-expression-+ 


PUSH stacks the string resulting from the evaluation of expression LIFO (Last In, First Out) into the 
external data queue. (See Input and Output Streams for a discussion of Rexx input and output.) 


If you do not specify expression, a null string is stacked. 


Example: 
a="Fred" 
push /* Puts a null line onto the queue */ 
push a2 /* Puts "Fred 2" onto the queue */ 


The QUEUED built-in function (described in QUEUED) returns the number of lines currently in the 
external data queue. 


2.22. QUEUE 


»»-QUEUE--4------------ %--;------------------------------------ >< 
+-expression-+ 
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QUEUE appends the string resulting from expression to the tail of the external data queue. That is, it is 
added FIFO (First In, First Out). (See Input and Output Streams for a discussion of Rexx input and 
output.) 


If you do not specify expression, a null string is queued. 


Example: 


a="Toft" 
queue a 2 /* Enqueues "Toft 2" ж/ 
queue /* Enqueues a null line behind the last */ 


The QUEUED built-in function (described in QUEUED) returns the number of lines currently in the 
external data queue. 


2.23. RAISE 


>>-RAISE--+-condition------------ a +-------- >< 
*-ERROR--errorcode----- + +-| options |-* 
+-FAILURE--failurecode-+ 
*t-SYNTAX--number------- * 
+-USER--usercondition--+ 
+-РЕПРАСАТЕ-----------< + 
options: 
|--%------------------------ %--%-------------------- %----------- > 
+-ADDITIONAL--expra------ + +-DESCRIPTION--exprd-+ 
| +-,----- + | 
| V | | 


+-| EXIT |---------- + 
>--%------------------- %---------------------------------------- 
*-RETURN--4------- +-+ 


ЕХП: 


| --EXIT--4------- %---------------------------------------------- 


Note: You сап specify the options ADDITIONAL, ARRAY, DESCRIPTION, RETURN, and EXIT in 
any order. However, if you specify EXIT without expre or RETURN without exprr, it must appear last. 


RAISE returns or exits from the currently running routine or method and raises a condition in the caller 
(for a routine) or sender (for a method). See Conditions and Condition Traps for details of the actions 
taken when conditions are raised. The RAISE instruction can raise all conditions that can be trapped. 


If you specify condition, it is a single symbol that is taken as a constant. 
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If the ERROR or FAILURE condition is raised, you must supply the associated return code as errorcode 
or failurecode, respectively. These can be literal strings, constant symbols, or expressions enclosed in 
parentheses. If you specify an expression enclosed in parentheses, a subexpression, the language 
processor evaluates the expression to obtain its character string value. 


If the SYNTAX condition is raised, you must supply the associated Rexx error number as number. This 
error number can be either a Rexx major error code or a Rexx detailed error code in the form nn.nnn. The 
number can be a literal string, a constant symbol, or an expression enclosed in parentheses. If you 
specify an expression enclosed in parentheses, the language processor evaluates the expression to obtain 
its character string value. 


If a USER condition is raised, you must supply the associated user condition name as usercondition. This 
can be a literal string or a symbol that is taken as a constant. 


If you specify the ADDITIONAL option, the language processor evaluates expra to produce an object 
that supplies additional object information associated with the condition. The expra can be a literal string, 
constant symbol, or expression enclosed in parentheses. The ADDITIONAL entry of the condition object 
and the "A" option of the CONDITION built-in function return this additional object information. For 
SYNTAX conditions, the ADDITIONAL value must evaluate to a single-dimension Rexx array object. 


If you specify the ARRAY option, each expri is an expression (use commas to separate the expressions). 
The language processor evaluates the expression list to produce an array object that supplies additional 
object information associated with the condition. The ADDITIONAL entry of the condition object and 
the "A" option of the CONDITION built-in function return this additional object information as an array 
of values. It is an error to use both the ARRAY option and the ADDITIONAL option on the same RAISE 
instruction. 


The content of expra or expri is used as the contents of the secondary error message produced for a 
condition. 


If you specify neither ADDITIONAL nor ARRAY, there is no additional object information associated 
with the condition. 


If you specify the DESCRIPTION option, the exprd can be a literal string, a constant symbol, or an 
expression enclosed in parentheses. If you specify an expression enclosed in parentheses, the language 
processor evaluates the expression to obtain its character string value. This is the description associated 
with the condition. The "D" option of the CONDITION built-in function and the DESCRIPTION entry 
of the condition object return this string. 


If you do not specify DESCRIPTION, the language processor uses a null string as the descriptive string. 


If you specify the RETURN or EXIT option, the language processor evaluates the expression exprr or 
expre, respectively, to produce a result object that is passed back to the caller or sender as if it were a 
RETURN or EXIT result. The expre or exprr is a literal string, constant symbol, or expression enclosed 
in parentheses. If you specify an expression enclosed in parentheses, the language processor evaluates 
the expression to obtain its character string value. If you do not specify exprr or expre, no result is passed 
back to the caller or sender. In either case, the effect is the same as that of the RETURN or EXIT 
instruction (see RETURN). Following the return or exit, the appropriate action is taken in the caller or 
sender (see Action Taken when a Condition Is Not Trapped). If specified, the result value can be obtained 
from the RESULT entry of the condition object. 


Examples: 


raise syntax 40 /* Raises syntax error 40 ж/ 
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raise syntax 40.12 array (1, number) /* Raises syntax error 40, subcode 12 ж/ 
/* Passing two substitution values */ 
raise syntax (errnum) /* Uses the value of the variable ERRNUM */ 
/* as the syntax error number ж/ 
raise user badvalue /* Raises user condition BADVALUE */ 


If you specify PROPAGATE, and there is a currently trapped condition, this condition is raised again in 
the caller (for a routine) or sender (for a method). Any ADDITIONAL, DESCRIPTION, ARRAY, 
RETURN, or EXIT information specified on the RAISE instruction replaces the corresponding values 
for the currently trapped condition. A SYNTAX error occurs if no condition is currently trapped. 


Example: 


signal on syntax 


ас "ху2 " 
c = at2 /* Raises the SYNTAX condition */ 
exit 
syntax: 
raise propagate /* Propagates SYNTAX information to caller */ 


2.24. REPLY 


>>-REPLY--+------------ %--;------------------------------------ >< 
+-expression-+ 


REPLY sends an early reply from a method to its caller. The method issuing REPLY returns control, and 
possibly a result, to its caller to the point from which the message was sent; meanwhile, the method 
issuing REPLY continues running on a newly created thread. 


If you specify expression, it is evaluated and the object resulting from the evaluation is passed back. If 
you omit expression, no object is passed back. 


Unlike RETURN or EXIT, the method issuing REPLY continues to run after the REPLY until it issues an 
EXIT or RETURN instruction. The EXIT or RETURN must not specify a result expression. 


Example: 

reply 42 /* Returns control and a result ж/ 
call tidyup /* Can run in parallel with sender */ 
return 

Notes: 


1. You can use REPLY only in a method. 
2. A method can execute only one REPLY instruction. 


3. When the method issuing the REPLY instruction is the only active method on the current thread with 
exclusive access to the object’s variable pool, the method retains exclusive access on the new thread. 
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When other methods on the thread also have access, the method issuing the REPLY releases its 
access and reacquires the access on the new thread. This might force the method to wait until the 
original activity has released its access. 


See Concurrency for a complete description of concurrency. 


2.25. RETURN 


S»cRETURN--£------25----- qoeQgenccezceeeneeeeceecueuneeeocceeeseceecos >< 
+-expression-+ 


RETURN returns control, and possibly a result, from a Rexx program, method, or routine to the point of 
its invocation. 


If no internal routine (subroutine or function) is active, RETURN and EXIT are identical in their effect 
on the program that is run. (See EXIT.) 


If called as a routine, expression (if any) is evaluated, control is passed back to the caller, and the Rexx 
special variable RESULT is set to the value of expression. If you omit expression, the special variable 
RESULT is dropped (becomes uninitialized). The various settings saved at the time of the CALL (for 
example, tracing and addresses) are also restored. (See CALL.) 


If a function call is active, the action taken is identical, except that expression must be specified on the 
RETURN instruction. The result of expression is then used in the original expression at the point where 
the function was called. See the description of functions in Functions for more details. 


If a method is processed, the language processor evaluates expression (if any) and returns control to the 
point from which the method’s activating message was sent. If called as a term of an expression, 
expression is required. If called as a message instruction, expression is optional and is assigned to the 
Rexx special variable RESULT if a return expression is specified. If the method has previously issued a 
REPLY instruction, the RETURN instruction must not include a result expression. 


If a PROCEDURE instruction was processed within an internal subroutine or internal function, all 
variables of the current generation are dropped (and those of the previous generation are exposed) after 
expression is evaluated and before the result is used or assigned to RESULT. 


Note: If the RETURN statement causes the program to return to the operating system on a 
Unix/Linux system the value returned is limited to a numerical value between 0 and 255 (an unsigned 
byte). If no expression is supplied then the default value returned to the operating system is zero. 


2.26. SAY 


»»-SAY--4------------ %--;-------------------------------------- >< 
+-expression-+ 


SAY writes a line to the default output stream, which displays it to the user. However, the output 
destination can depend on the implementation. See Input and Output Streams for a discussion of Rexx 
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input and output. The string value of the expression result is written to the default character output 


stream. The resulting string can be of any length. If you omit expression, the null string is written. 


The SAY instruction is a shorter form of the following instruction: 


>>-CALL LINEOQUT , --+------------ Lom ------------- >< 
+-expression-+ 


except that: 


* SAY does not affect the special variable RESULT. 

* If you use SAY and omit expression, a null string is used. 

* CALL LINEOUT can raise NOTREADY; SAY will not. 

See LINEOUT (Line Output) for details of the LINEOUT function. 


Example: 


data-100 
Say data "divided by 4 =>" data/4 
/* Displays: "100 divided by 4 => 25" */ 


Notes: 


1. Data from the SAY instruction is sent to the default output stream (.DUTPUT). However, the 
standard rules for redirecting output apply to the SAY output. 


2. The SAY instruction does not format data; the operating system and the hardware handle line 
wrapping. However, formatting is accomplished, the output data remains a single logical line. 


2.27. SELECT 


»»-SELECT---4------------- a аорта аас ае а uu > 
+-LABEL--name-+ 


%------------------------------------------------------ + 
V | 
>----WHEN--expression--+---+--THEN--+---+--instruction-- ;-+------> 
+=: =+ Жеф 
See Ase SS Sea --------------------- +-ЕМр-+--------+-;->< 
T-ÜTHERWISE--f--—4--4--——---------------- Tt +--паше--+ 
t-;-+ | +---------------- + | 
| V | | 
+---instruction--;-+-+ 


SELECT conditionally calls one of several alternative instructions. 


Each expression after a WHEN is evaluated in turn and must result in 0 or 1. If the result is 1, the 
instruction following the associated THEN (which can be a complex instruction such as IF, DO, LOOP, 
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or SELECT) is processed and control is then passed to the END. If the result is 0, control is passed to the 
next WHEN clause. 


If none of the WHEN expressions evaluates to 1, control is passed to the instructions, if any, after 
OTHERWISE. In this situation, the absence of an OTHERWISE produces an error, however, you can 
omit the instruction list that follows OTHERWISE. 


Example: 


balance=100 
check=50 
balance = balance - check 
Select 
when balance > 0 then 
say "Congratulations! You still have" balance "dollars left." 
when balance = O then do 
say "Warning, Balance is now zero! STOP all spending." 
say "You cut it close this month! Hope you do not have any" 
say "checks left outstanding." 
end 
Otherwise do 
say "You have just overdrawn your account." 
say "Your balance now shows" balance "dollars." 
say "Oops! Hope the bank does not close your account." 
end 
end /* Select */ 
/ 


The expression may also be a list of expressions separated by ",". Each subexpression must evaluate to 
either 0 or 1. The list of expressions is evaluated left-to-right. Evaluation will stop with the first 0 result 
and 0 will be returned as the condition result. If all of the subexpressions evaluate to 1, then the condition 
result is also 1. 


Example: 


select 


when answer~datatype(’w’), answer//2 = 0 Then 
say answer "is even" 

when answer~datatype(’w’), answer//2 = 1 Then 
say answer "is odd" 

otherwise 
say answer "is not a number" 


end 
The example above is not the same as using the following 


select 


when answer~datatype(’w’) & answer//2 = 0 Then 
say answer "is even" 

when answer~datatype(’w’) & answer//2 = 1 Then 
say answer "is odd" 

otherwise 
say answer "is not a number" 


end 
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The logical & operator will evaluate both terms of the operation, so the term "answer//2" will result in a 
syntax error if answer is a non-numeric value. With the list conditional form, evaluation will stop with 
the first false result, so the "answer//2" term will not be evaluated if the datatype test returns 0 (.false). 


Notes: 


1. The instruction can be any assignment, command, message instruction, or keyword instruction, 
including any of the more complex constructs, such as DO, LOOP, IF, or the SELECT instruction 


itself. 


2. A null clause is not an instruction, so putting an extra semicolon (or label) after a THEN clause is 
not equivalent to putting a dummy instruction. The NOP instruction is provided for this purpose. 


3. The symbol THEN cannot be used within expression, because the keyword THEN is treated 
differently in that it need not start a clause. This allows the expression on the WHEN clause to be 


ended by the THEN without a semicolon (;). 


2.28. SIGNAL 


»»-SIGNAL------------------------------------------------------- 
2-cf-labelname---z-----2---5------5pe5esto0nocecnenco Sa a >< 
аа ааа + охргевятоп---------р tase SSS SaaS sae + 
| +-VALUE-+ | 
T-Ü0FF--4-ANY----------------- Уже at a a aa + 
| +-ERROR--------------- + | 
| +-FAILURE------------- + | 
| +-HALT---------------- + | 
| *-LOSTDIGITS---------- * | 
| +-МОМЕТНОр------------ + | 
| +-NOSTRING------------ + | 
| +-NOTREADY------------ + | 
| +-NOVALUE------------- + | 
| T-SYNTAX-------------- + | 
| +-USER--usercondition-+ 
+-QN--+-ANY----------------- %--%---------------- +-+ 
*t-ERRÜR---------2—----- + +-NAME--trapname-+ 
*-FAILURE------------- * 
*-HALT---------------- * 
*-LOSTDIGITS---------- + 
*-NOMETHOD------------ * 
*-NOSTRING------------ * 
*-NOTREADY------------ * 
*-NOVALUE------------- * 
*-SYNTAX-------------- * 


+-USER--usercondition-+ 


SIGNAL causes an unusual change in the flow of control (if you specify labelname or VALUE 
expression), or controls the trapping of certain conditions (if you specify ON or OFF). 
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To control trapping, you specify OFF or ON and the condition you want to trap. OFF turns off the 
specified condition trap. ON turns on the specified condition trap. All information on condition traps is 
contained in Conditions and Condition Traps. 


To change the flow of control, a label name is derived from /abelname or taken from the character string 
result of evaluating the expression after VALUE. The labelname you specify must be a literal string or 
symbol that is taken as a constant. If you specify a symbol for labelname, the search looks for a label 
with uppercase characters. If you specify a literal string, the search uses the literal string directly. You 
can locate label names with lowercase letters only if you specify the label as a literal string with the same 
case. Similarly, for SIGNAL VALUE, the lettercase of labelname must match exactly. You can omit the 
subkeyword VALUE if expression does not begin with a symbol or literal string, that is, if it starts with a 
special character, such as an operator character or parenthesis. All active pending DO, IF, SELECT, and 
INTERPRET instructions in the current routine are then ended and cannot be resumed. Control is then 
passed to the first label in the program that matches the given name, as though the search had started at 
the beginning of the program. 


The labelname and usercondition are single symbols, which are taken as constants. The trapname is a 
string or symbol taken as a constant. 


Example: 


Signal fred; /* Transfer control to label FRED below ж/ 


Fred: say "Hi!" 
If there are duplicates, control is always passed to the first occurrence of the label in the program. 


When control reaches the specified label, the line number of the SIGNAL instruction is assigned to the 
special variable SIGL. This can aid debugging because you can use SIGL to determine the source of a 
transfer of control to a label. 


2.29. TRACE 


»»-TRACE--4-4-------- %----------------------- %--;-------------- >< 
| +-number-+ | 
| *-Normal-------- * | 
%-%----------- %--4--------------- +-+ 
| +------- + | %-Д11----------- + 
| V | | *-Commands------ + 
Же-еее ===}, “4-Егког--------- + 
+-Failure------- + 


+-Intermediates-+ 


+-Labels-------- + 
*-0ff----------- * 
*t-Results------- * 
Or, alternatively: 
>>-TRACE--+----------------------- fe ee seer a >< 
T-SUrlhg-------—--—----— + 
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T-symbol-------—-—--——--- + 
qeke—————- +--expression-+ 
+-VALUE-+ 


TRACE controls the tracing action (that is, how much is displayed to the user) during the processing of a 
Rexx program. Tracing describes some or all of the clauses in a program, producing descriptions of 
clauses as they are processed. TRACE is mainly used for debugging. Its syntax is more concise than that 
of other Rexx instructions because TRACE is usually entered manually during interactive debugging. 
(This is a form of tracing in which the user can interact with the language processor while the program is 
running.) 


Note: TRACE cannot be used in the Rexx macrospace. See Trace in Macrospace. 


If specified, the number must be a whole number. 


The string or expression evaluates to: 


* A numeric option 


* One of the valid prefix or alphabetic character (word) options described in Trace Alphabetic Character 
(Word) Options 


* Null 


The symbol is taken as a constant and is therefore: 


* А numeric option 


* One of the valid prefix or alphabetic character (word) options described in Alphabetic Character 
(Word) Options 


The option that follows TRACE or the character string that is the result of evaluating expression 
determines the tracing action. You can omit the subkeyword VALUE if expression does not begin with a 
symbol or a literal string, that is, if it starts with a special character, such as an operator or parenthesis. 


2.29.1. Trace Alphabetic Character (Word) Options 


Although you can enter the word in full, only the first capitalized letter is needed; all following 
characters are ignored. That is why these are referred to as alphabetic character options. 


TRACE actions correspond to the alphabetic character options as follows: 
All 
Traces (that is, displays) all clauses before execution. 


Commands 


Traces all commands before execution. If the command results in an error or failure (see 
Commands), tracing also displays the return code from the command. 
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Error 
Traces any command resulting in an error or failure after execution (see Commands), together with 
the return code from the command. 

Failure 
Traces any command resulting in a failure after execution (see Commands), together with the return 
code from the command. This is the same as the Normal option. 

Intermediates 
Traces all clauses before execution. Also traces intermediate results during the evaluation of 
expressions and substituted names. 

Labels 


Traces only labels passed during execution. This is especially useful with debug mode, when the 
language processor pauses after each label. It also helps the user to note all internal subroutine calls 
and transfers of control because of the SIGNAL instruction. 


Normal 


Traces any failing command after execution, together with the return code from the command. This 
is the default setting. 


For the default Windows command processor, an attempt to enter an unknown command raises a 
FAILURE condition. The CMD return code for an unknown command is 1. An attempt to enter a 
command in an unknown command environment also raises a FAILURE condition; in such a case, 
the variable RC is set to 30. 


Off 


Traces nothing and resets the special prefix option (described later) to OFF. 


Results 


Traces all clauses before execution. Displays the final results (in contrast with Intermediates 
option) of the expression evaluation. Also displays values assigned during PULL, ARG, PARSE, 
and USE instructions. This setting is recommended for general debugging. 


2.29.2. Prefix Option 


The prefix ? is valid alone or with one of the alphabetic character options. You can specify the prefix 
more than once, if desired. Each occurrence of a prefix on an instruction reverses the action of the 
previous prefix. The prefix must immediately precede the option (no intervening whitespace). 


The prefix ? controls interactive debugging. During normal execution, a TRACE option with a prefix of ? 
causes interactive debugging to be switched on. (See Debugging Aids for full details of this facility.) 
When interactive debugging is on, interpretation pauses after most clauses that are traced. For example, 
the instruction TRACE ?E makes the language processor pause for input after executing any command that 
returns an error, that is, a nonzero return code or explicit setting of the error condition by the command 
handler. 
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Any TRACE instructions in the program being traced are ignored to ensure that you are not taken out of 
interactive debugging unexpectedly. 


You can switch off interactive debugging in several ways: 


* Entering TRACE 0 turns off all tracing. 


* Entering TRACE with no options restores the defaults—it turns off interactive debugging but continues 
tracing with TRACE Normal (which traces any failing command after execution). 


* Entering TRACE ? turns off interactive debugging and continues tracing with the current option. 


* Entering a TRACE instruction with a ? prefix before the option turns off interactive debugging and 
continues tracing with the new option. 


Using the ? prefix, therefore, switches you in or out of interactive debugging. Because the language 
processor ignores any further TRACE statements in your program after you are in interactive debug 
mode, use CALL TRACE "?" to turn off interactive debugging. 


2.29.3. Numeric Options 


If interactive debugging is active and the option specified is a positive whole number (or an expression 
that evaluates to a positive whole number), that number indicates the number of debug pauses to be 
skipped. (See Debugging Aids for further information.) However, if the option is a negative whole 
number (or an expression that evaluates to a negative whole number), all tracing, including debug pauses, 
is temporarily inhibited for the specified number of clauses. For example, TRACE -100 means that the 
next 100 clauses that would usually be traced are not displayed. After that, tracing resumes as before. 


2.29.3.1. Tracing Tips 


* Whenaloop is traced, the DO clause itself is traced on every iteration of the loop. 


* Youcan retrieve the trace actions currently in effect by using the TRACE built-in function (see 
TRACE). 


* The trace output of commands traced before execution always contains the final value of the 
command, that is, the string passed to the environment, and the clause generating it. 


* Trace actions are automatically saved across subroutine, function, and method calls. See CALL for 
more details. 


2.29.3.2. Example 


One of the most common traces you will use is: 


TRACE ?R 
/* Interactive debugging is switched on if it was off, */ 
/* and tracing results of expressions begins. ж/ 
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2.29.3.3. The Format of Trace Output 


Every clause traced appears with automatic formatting (indentation) according to its logical depth of 


nesting, for example. Results, if requested, are indented by two extra spaces and are enclosed in double 


quotation marks so that leading and trailing whitespace characters are apparent. Any control codes in the 
data encoding (ASCII values less than "20"x) are replaced by a question mark (?) to avoid screen 
interference. Results other than strings appear in the string representation obtained by sending them a 


STRING message. The resulting string is enclosed in parentheses. The line number in the program 


precedes the first clause traced on any line. All lines displayed during tracing have a three-character 
prefix to identify the type of data being traced. These can be: 


+++ 


>>> 


Identifies the source of a single clause, that is, the data actually in ће program. 


Identifies a trace message. This can be the nonzero return code from a command, the prompt 
message when interactive debugging is entered, an indication of a syntax error when in interactive 
debugging. 


Identifies the result of an expression (for TRACE R) or the the value returned from a subroutine call, 
or a value evaluated by execution of a DO loop. 


Identifies a variable assignment or a message assignment result. The trace message includes both 
the name of the assignment target and the assigned value. Assignment trace lines are displayed by 
assignment instructions, variable assigned via PARSE, ARG, PULL, or USE ARG, as well as 
control variable updates for DO and LOOP instructions. 


Identifies the value assigned to a placeholder during parsing (see The Period as a Placeholder). 


The following prefixes are used only if TRACE Intermediates is in effect: 


>A> 


>C> 


>E> 


>F> 


Identifies a value used as a function, subroutine, or message argument. 


The data traced is the orignal name of the compound variable and the name of a compound variable, 
after the name has been replaced by the value of the variable but before the variable is used. If no 
value was assigned to the variable, the trace shows the variable in uppercase characters. 


The data traced is the name and value of an environment symbol. 


The data traced is the name and result of a function call. 
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>L> 


The data traced is a literal (string, uninitialized variable, or constant symbol). 


>M> 


The data traced is the name and result of an object message. 


>0> 


The data traced is the name and result of an operation on two terms. 


>P> 


The data traced is the name and result of a prefix operation. 


>V> 


The data traced is the name and contents of a variable. 


Note: The characters => indicate the value of a variable or the result of an operation. 


The characters <= indicate a value assignment. The name to the left of the marker is the assignment 
topic. The data to the right of the marker is the assigned value. 


The character ? could indicate a non-printable character in the output. 


If no option is specified on a TRACE instruction, or if the result of evaluating the expression is null, the 
default tracing actions are restored. The defaults are TRACE N and interactive debugging (?) off. 


Following a syntax error that SIGNAL ON SYNTAX does not trap, the clause in error is always traced. 


2.30. USE 


»»-USE--4----------- *--ARG----4-------------------- %-%----------------------- >< 
%-- STRICT--+ +-паше-+---------- TN 
+-=--ехрг--+ 


USE ARG retrieves the argument objects provided in a program, routine, function, or method and 
assigns them to variables or message term assignments. 


Each name must be a valid variable name. The names are assigned from left to right. For each name you 
specify, the language processor assigns it a corresponding argument from the program, routine, function, 
or method call. If there is no corresponding argument, name is assigned the value of expr. If expr is not 
specified for the given argument, the variable name is dropped. If the assignment target is a messaging 
term, no action is taken for omitted arguments. 


A USE ARG instruction can be processed repeatedly and it always accesses the same current argument 
data. 
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If expr is specified for an argument, the expression is evaluated to provide a default value for an 
argument when the corresponding argument does not exist. The default expr must be a literal string, a 
constant expression, or an expression enclosed in parentheses. 


The names may be any valid symbol or message term which can appear on the left side of an assignment 
statement (See Assignments and Symbols). 


The STRICT options imposes additional constraints on argument processing. The number of arguments 
must match the number of names, otherwise an error is raised. An argument may be considered optional 
if expr has been specified for the argument. 


The ellipsis ("...") сап be given in place of the last variable in the USE STRICT ARG statement and 
indicates that more arguments may follow. It allows defining a minimum amount of arguments that must 
be supplied or for which there are default values defined and that may be followed optionally by any 
additional arguments. 


Example: 
/* USE Example ж/ 


/* FRED("Ogof Х",1,5) calls function ж/ 
Fred: use arg string, numi, num2 


/* Now: STRING contains "Ogof X" ж/ 
/ж NUM1 contains "1" ж/ 
/ж NUM2 contains "5" ж/ 


/* Another example, shows how to pass non-string arguments with USE ARG */ 
/* Pass a stem and an array to a routine to modify one element of each */ 


stem.1 = "Value" 

array = .array~of("Item") 

say "Before subroutine:" stem.1 аггау [1] /ж Shows "Value Item" ж/ 
Call Change_First stem. , array 

say "After subroutine:" stem.1 array[1] /ж Shows "NewValue NewItem" ж/ 
Exit 


Change First: Procedure 
Use Arg substem., subarray 


substem.1 - "NewValue" 
subarray[1] = "NewItem" 
Return 
/* USE STRICT Example ж/ 


/* FRED("Ogof X",1) calls function ж/ 
Fred: use strict arg string, numi, num2-4 


/* Now: STRING contains "Ogof X" ж/ 
/ж NUM1 contains "1" ж/ 
/ж NUM2 contains "4" ж/ 


In the above example, a call to the function FRED may have either 2 or 3 arguments. Тһе STRICT 
keyword on the USE instruction will raise a syntax error for any other combination of arguments. 


Example: 


call test "one" 
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call test "one", "two" 

call test "one", "two", "three" 

call test "one", , "three", "four", "five" 
exit 


test: procedure /* a minimum of one argument must be supplied */ 
use strict arg vi, v2-"zwei", 
say "There are ["arg()"] argument(s); vi,v2-["vi","v2"]" 
do i-3 to argO 
say " arg it" i"-["arg(i)"]" 
end 
say "--" 
return 


Output: 


There are [1] argument(s); vi,v2-[one,zwei] 


There are [2] argument(s); vi,v2-[one,two] 


There are [3] argument(s); vi,v2-[one,two] 
arg # 3-[three] 


There are [5] argument(s); vi,v2-[one,zwei] 
arg # 3-[three] 
arg # 4=[four] 
arg # 5=[five] 


The assignment targets may be any term that can be on the left side of an assignment statement. For 
example, 


expose myArray myDirectory 
use arg myArray[1], myDirectory^name 


would be equivalent to 


myArray[1] = arg(1) 
myDirectory^name = arg(2) 


You can retrieve or check the arguments by using the ARG built-in function (see ARG (Argument)). The 
ARG and PARSE ARG instructions are alternative ways of retrieving arguments. ARG and PARSE ARG 
access the string values of arguments. USE ARG performs a direct, one-to-one assignment of arguments. 
This is preferable when you need direct access to an argument, without translation or parsing. USE ARG 
also allows access to both string and non-string argument objects; ARG and PARSE ARG convert the 
arguments to values before parsing. 
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A Rexx program contains one or more executable code units. Directive instructions separate these 
executable units. A directive begins with a double colon (::) and is a nonexecutable instruction. For 
example, it cannot appear in a string for the INTERPRET instruction to be interpreted. The first directive 
instruction in a program marks the end of the main executable section of the program. 


For a program containing directives, all directives are processed first to set up the program’s classes, 
methods, and routines. Then any program code in the main code unit (preceding the first directive) is 
processed. This code can use any classes, methods, and routines that the directives established. 


3.1. : ATTRIBUTE 


The :: ATTRIBUTE directive creates attribute methods and defines the method properties. 


>>-: :АТТЕТВОТЕ--паше--+----- Ф-===-== SSS ees фе-чее------<--т-----т-с---ы > 
+-GET-+ +-CLASS-+ 
+-SET-+ 


+-PUBLIC--+ +-GUARDED---+ +-UNPROTECTED-+ 
>--+--------- +--+----------- +--+------------- %------------------- > 
+-PRIVATE-+ +-UNGUARDED-+ +-PROTECTED---+ 


>--%--------------- %---;----------------------------------------- >< 
+-EXTERNAL-spec-+ 


The :: ATTRIBUTE directive creates accessor methods for object instance variables. An accessor method 
allows an object instance variable to be retrieved or assigned a value. :: ATTRIBUTE can create an 
attribute getter method, a setter method, or the getter/setter pair. 


The name is a literal string or a symbol that is taken as a constant. The name must also be a valid Rexx 
variable name. The :: ATTRIBUTE directive creates methods in the class specified іп the most recent 

: CLASS directive. If no ::CLASS directive precedes an :: ATTRIBUTE directive, the attribute methods 
are not associated with a class but are accessible to the main (executable) part of a program through the 
.METHODS built-in object. Only one :: ATTRIBUTE directive can appear for any method name not 
associated with a class. See . METHODS for more details. 


If you do not specify either SET or GET, :: ATTRIBUTE will create two attribute methods with the 
names name and name=. These are the methods for getting and setting an attribute. These generated 
methods are equivalent to the following code sequences: 


::method "NAME-" /* attribute set method ж/ 
expose name /* establish direct access to object variable (attribute) */ 
use arg name /* retrieve argument and assign it to the object variable */ 

::method name /* attribute get method */ 
expose name /* establish direct access to object variable (attribute) */ 
return name /* return object's current value */ 
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Both methods will be created with the same method properties (for example, PRIVATE, GUARDED, 
etc.). If GET or SET are not specified, the pair of methods will be automatically generated. In that case, 
there is no method code body following the directive, so another directive (or the end of the program) 
must follow the :: ATTRIBUTE directive. 


If GET or SET is specified, only the single get or set attribute method is generated. Specifying separate 
GET or SET ::ATTRIBUTE directives allows the methods to be created with different properties. For 
example, the sequence: 


::attribute name get 
::attribute name set private 


will create a NAME method with PUBLIC access and a NAME= method with PRIVATE access. 


The GET and SET options may also be used to override the default method body generated for the 
attribute. This is frequently used so the SET attribute method can perform new value validation. 


::attribute size get 
::attribute size set 
expose size /* establish direct access to object variable (attribute) */ 
use arg value /* retrieve argument ж/ 
if datatype(value, "Whole") = .false | value < 0 then 
raise syntax 93.906 array ("size", value) 
size=value 


If you specify the CLASS option, the created methods are class methods. See Objects and Classes. The 
attribute methods are associated with the class specified on the most recent ::CLASS directive. The 
:: ATTRIBUTE must be preceded by a ::CLASS directive if CLASS is specified. 


If the EXTERNAL option is specified, then spec identifies a method in an external native library that will 
be invoked as the named method. The spec is a literal string containing a series of whitespace delimited 
tokens defining the external method. The first token must be the word LIBRARY, which indicates the 
method resides in a native library of the type allowed on a ::REQUIRES directive. The second token 
must identify the name of the external library. The external library is located using platform-specific 
mechanisms for loading libraries. For Unix-based systems, the library name is case-sensitive. The third 
token is optional and specifies the name of the method within the library package. If not specified, the 

:z METHOD name is used. The target package method name is case insensitive. 


If the SET or GET option is not specified with the EXTERNAL option, then two method objects need to 
be created. The target method name is appended to the string "GET" to derive the name of the getter 
attribute method. To generate the setter attribute method, the name is appended to the string "SET". If 
GET or SET is specified and the method name is not specified within spec, then the target library method 
name is generated by concatenating name with "GET" or "SET" as appropriate. If the method name is 
specified in spec and GET or SET is specified, the spec name will be used unchanged. 


Example: 


-- maps "NAME" method to "GETNAME and 

-- "NAME-" to "SETNAME" 

::ATTRIBUTE name EXTERNAL "LIBRARY mylib" 

-- maps "ADDRESS" method to "GETADDRESS" 

::ATTRIBUTE address GET EXTERNAL "LIBRARY mylib" 

-- maps "ADDRESS-" method to "setHomeAddress" 

::ATTRIBUTE address SET EXTERNAL "LIBRARY mylib setHomeAddress" 
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Notes: 


Ó 


. You can specify all options in any order. 


N 


. If you specify the PRIVATE option, the created methods are private methods. Private methods have 
restricted access rules on how they can be invoked. See Public versus Private Methods for details of 
how private methods can be used. If you omit the PRIVATE option or specify PUBLIC, the method 
is a public method that any sender can activate. 


|95) 


. If you specify the UNGUARDED option, the methods сап be called while other methods are active 
on the same object. If you do not specify UNGUARDED, the method requires exclusive use of the 
object variable pool; it can run only if no other method that requires exclusive use of the object 
variable pool is active on the same object. 


4. If you specify the PROTECTED option, the method methods are protected methods. (See The 
Security Manager for more information.) If you omit the PROTECTED option or specify 
UNPROTECTED, the methods are not protected. 


Nn 


. It is an error to specify :: ATTRIBUTE more than once within a class definition that creates a 
duplicate get or set method. 


3.2. ::CLASS 


The ::CLASS directive causes the interpreter to create a Rexx class. 


22-::CBABS--classname--t---------------------5 фев -------5 > 
*-METACLASS--metaclass--* 


.-SUBCLASS--Übject---. +-PRIVATE-+ 

»--4-------------------- +--+--------- %--4------------------- +--;-->< 
+-MIXINCLASS--mclass-+ +-PUBLIC--+ +-INHERIT--iclasses-+ 
*-SUBCLASS--sclass----* 


The ::CLASS directive creates a Rexx class named classname. The classname is a literal string or symbol 
that is taken as a constant. The created class is available to programs through the Rexx environment 
symbol .classname. The classname acquires all methods defined by subsequent :: METHOD directives 
until the end of the program or another ::CLASS directive is found. Only null clauses (comments or 
blank lines) can appear between a ::CLASS directive and any following directive instruction or the end 
of the program. Only one ::CLASS directive can appear for classname in a program. 


If you specify the METACLASS option, the instance methods of the metaclass class become class 
methods of the classname class. (See Objects and Classes .) The metaclass and classname are literal 
strings or symbols that are taken as constants. In the search order for methods, the metaclass methods 
precede inherited class methods and follow any class methods defined by :: METHOD directives with the 
CLASS option. 


If you specify the PUBLIC option, the class is visible beyond its containing Rexx program to any other 
program that references this program with a :: REQUIRES directive. (See :: REQUIRES.) If you do not 
specify the PUBLIC option, the class is visible only within its containing Rexx program. All public 
classes defined within a program are used before PUBLIC classes created with the same name. 
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If you specify the SUBCLASS option, the class becomes a subclass of the class sclass for inheritance of 
instance and class methods. The sclass is a literal string or symbol that is taken as a constant. 


If you specify the MIXINCLASS option, the class becomes a subclass of the class mclass for inheritance 
of instance and class methods. You can add the new class instance and class methods to existing classes 
by using the INHERIT option on a ::CLASS directive or by sending an INHERIT message to an existing 
class. If you specify neither the SUBCLASS nor the MIXINCLASS option, the class becomes a 
non-mixin subclass of the Object class. 


If you specify the INHERIT option, the class inherits instance methods and class methods from the 
classes iclasses in their order of appearance (leftmost first). This is equivalent to sending a series of 
INHERIT messages to the class object, with each INHERIT message (except the first) specifying the 
preceding class in iclasses as the classpos argument. (See INHERIT .) As with the INHERIT message, 
each of the classes in iclasses must be a mixin class. The iclasses is a whitespace-separated list of literal 
strings or symbols that are taken as constants. If you omit the INHERIT option, the class inherits only 
from sclass. 


Example: 


::class rectangle 

::method area /* defined for the RECTANGLE class */ 
expose width height 
return width*height 


::class triangle 

::method area /* defined for the TRIANGLE class */ 
expose width height 
return width*height/2 


The ::CLASS directives in a program are processed in the order in which they appear. If a ::CLASS 
directive has a dependency on ::CLASS directives that appear later in the program, processing of the 
directive is deferred until all of the class's dependencies have been processed. 


Example: 


::class savings subclass account /* requires the ACCOUNT class */ 
::method type 
return "a Savings Account" 


::class account 
::method type 
return "an Account" 


The Savings class in the preceding example is not created until the Account class that appears later in the 
program has been created. 


Notes: 


1. You can specify the options METACLASS, MIXINCLASS, SUBCLASS, and PUBLIC in any order. 
2. If you specify INHERIT, it must be the last option. 
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3.3. :: CONSTANT 


The :: CONSTANT directive creates methods that return constant values for a class and its instances. 


>>=: ООНБТАНТ--паше--тайце-----------<---- <<< > 


А ::CONSTANT directive defines a method that returns a constant value. This is useful for creating 
named constants associated with a class. 


The name is a literal string or a symbol that is taken as a constant. A method of the given name is created 
as both an instance method and a class method of the most recent ::CLASS directive. A ::CLASS 
directive is not required before a :: CONSTANT directive. If no ::CLASS directive precedes 
(CONSTANT, a single constant method method is created that is not associated with a class but is 
accessible to the main (executable) part of a program through the METHODS built-in object. Only one 
(CONSTANT directive can appear for any method name not associated with a class. See METHODS 
for more details. 


The methods created by a :: CONSTANT directive are UNGUARDED and will have a return result that is 
specified by value. The constant value must be a single literal string or symbol that is taken as a constant. 
Also permitted is the single character "-" or "+" followed by a literal string or symbol that is a valid 
number. Here are some examples of valid constants: 


"on" 


::class MathConstants public 
::constant pi 3.1415926 ::constant author "Isaac Asimov" 
::constant absolute zero -273.15 


A ::CONSTANT directive is a shorthand syntax for creating constants associated with a class. The 
created name constant can be accessed using either the class object or an instance of the class itself. For 


example: 

say "Pi is" .MathConstants^pi -- displays "Pi is 3.1415926" 
instance = .MathConstants^new 

say "Pi is" instance^pi -- also displays "Pi is 3.1415926" 


::class MathConstants public 
::constant pi 3.1415926 


3.4. :: METHOD 


The :: METHOD directive creates a method object and defines the method attributes. 


2»-::METHOD--methodname---4------- qpo-R----------25 T-—R—————---- +---> 
+-CLASS-+ +-ATTRIBUTE-+ +-ABSTRACT-+ 


+-PUBLIC--+ +-GUARDED---+ +-UNPROTECTED-+ 
>--+--------- +--+----------- +--+------------- %------------------- > 


+-PRIVATE-+ +-UNGUARDED-+ +-PROTECTED---+ 


>--%--------------- %---;----------------------------------------- >< 
+-EXTERNAL-spec-+ 
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А :: METHOD directive creates method objects that may be associated with a class instance. The created 
method may be from Rexx code, mapped to method in an external native library, or automatically 
generated. The type of method is determined by the combination of options specified. 


The methodname is a literal string or a symbol that is taken as a constant. The method is defined as 
methodname in the class specified in the most recent ::CLASS directive. Only one :: METHOD directive 
can appear for any methodname in a class. 


A ::CLASS directive is not required before a :: METHOD directive. If no ::CLASS directive precedes 

z METHOD, the method is not associated with a class but is accessible to the main (executable) part of a 
program through the METHODS built-in object. Only one :: METHOD directive can appear for any 
method name not associated with a class. See METHODS for more details. 


If you specify the CLASS option, the method is a class method. See Objects and Classes. The method is 
associated with the class specified on the most recent ::CLASS directive. The :: METHOD directive must 
follow a ::CLASS directive when the CLASS option is used. 


If ABSTRACT, ATTRIBUTE, or EXTERNAL is not specified, the :: METHOD directive starts a section 
of method code which is ended by another directive or the end of the program. The :: METHOD is not 
included in the source of the created METHOD object. 


Example: 


г = .rectangle~new(20, 10) 
say "Area is" r “area /* Produces "Area is 200" */ 


::class rectangle 


::method area /* defined for the RECTANGLE class */ 
expose width height 
return width*height 


:imethod init 
expose width height 
use arg width, height 


::method perimeter 
expose width height 
return (widththeight)*2 


If you specify the ATTRIBUTE option, method variable accessor methods are created. In addition to 
generating a method named methodname, another method named methodname= is created. The first 
method returns the value of object instance variable that matches the method name. The second method 
assigns a new value to the object instance variable. 


For example, the directive 
::method name attribute 


creates two methods, NAME and NAME-. The NAME and МАМЕ- methods are equivalent to the 
following code sequences: 


::method "NAME=" 
expose name 
use arg name 
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::method name 
expose name 
return name 


If you specify the ABSTRACT option, the method creates an ABSTRACT method placeholder. 
ABSTRACT methods define a method that an implementing subclass is expected to provide a concrete 
implementation for. Any attempt to invoke an ABSTRACT method directly will raise a SYNTAX 
condition. 


If the EXTERNAL option is specified, then spec identifies a method in an external native library that will 
be invoked as the named method. The spec is a literal string containing a series of whitespace delimited 
tokens defining the external method. The first token must be the word LIBRARY, which indicates the 
method resides in a native library of the type allowed on a ::REQUIRES directive. The second token 
must identify the name of the external library. The external library is located using platform-specific 
mechanisms for loading libraries. For Unix-based systems, the library name is case-sensitive. The third 
token is optional and specifies the name of the method within the library package. If not specified, the 

: METHOD name is used. The target package method name is case insensitive. 


Example: 


-- creates method INIT from method RegExp Init 
-- in library rxregexp 
::METHOD INIT EXTERNAL "LIBRARY rxregexp RegExp Init" 


-- creates method INIT from method POS 
-- in library rxregexp 
::METHOD POS EXTERNAL "LIBRARY rxregexp" 


If the ATTRIBUTE option is specified with the EXTERNAL option, then two method objects need to be 
created. The target method name is appended to the string "GET" to derive the name of the getter 
attribute method. To generate the setter attribute method, the name is appended to the string "SET". 


Example: 


-- maps "NAME" method to "GETNAME and 
-- "NAME=" to "SETNAME" 
::METHOD name ATTRIBUTE EXTERNAL "LIBRARY mylib" 


-- maps "ADDRESS" method to "GETMyAddress and 
-- "ADDRESS-" to "SETMyAddress" 
::METHOD address ATTRIBUTE EXTERNAL "LIBRARY mylib MyAddress" 


Notes: 


1. You can specify all options in any order. 


2. If you specify the PRIVATE option, the created methods are private methods. Private methods have 
restricted access rules on how they can be invoked. See Public versus Private Methods for details of 
how private methods can be used. If you omit the PRIVATE option or specify PUBLIC, the method 
is a public method that any sender can activate. 


3. If you specify the UNGUARDED option, the method can be called while other methods are active 
on the same object. If you do not specify UNGUARDED, the method requires exclusive use of the 
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object variable pool; it can run only if no other method that requires exclusive use of the object 
variable pool is active on the same object. 


4. If you specify the PROTECTED option, the method is a protected method. (See The Security 
Manager for more information.) If you omit the PROTECTED option or specify UNPROTECTED, 
the method is not protected. 


5. If you specify ATTRIBUTE, ABSTRACT, or EXTERNAL, another directive (or the end of the 
program) must follow the :: METHOD directive. 


6. It is an error to specify :: METHOD more than once within the same class and use the same 
methodname. 


3.5. ::OPTIONS 


The ::OPTIONS directive defines default values for numeric and trace settings for all Rexx code 
contained within a package. 


»»-::0PTIONS--4--------------- +--+----------- +--+----------- +----> 
+-DIGITS-digits-+ +-FORM-form-+  *-FUZZ-fuzz-* 


>------------ %------------- %------------------------------------ >< 
+-TRACE-trace-+ 


Any of the options may be specified on a single ::OPTIONS directive in any order. If an option is 
specified more than once, the last specified value will the be one used. If more than one ::OPTIONS 
directive appears in a source file, the options are processed in the order they appear and the effect is 
accumulative. If a given option type is specified on more than directive, the last specified will be the 
value used. 


The specified options will override the normal default settings for all Rexx code contained in the source 
file. For example, 


::0PTIONS DIGITS 20 


would direct that all method and routine code defined in this source package execute with an initial 
NUMERIC DIGITS setting of 20 digits. The ::OPTIONS directive controls only the initial setting. A 
method or routine may change the current setting with the NUMERIC DIGITS instruction as normal. 
The values specified with ::OPTIONS only apply to code that appears in the same source file. It does not 
apply to code in other source files that may reference or use this code. For example, a subclass of a class 
defined in this source package will not inherit the :: OPTIONS settings if the subclass code is located in a 
different source package. 


The following options may be specified on an ::OPTIONS directive: 
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controls the precision to which arithmetic operations and built-in functions are 
evaluated. The value digits must be a symbol or string that is a valid positive whole 
number value and must be larger than the current FUZZ ::OPTIONS setting. The 
package value can be retrieved using the Package class digits method. 

There is no limit to the value for DIGITS (except the amount of storage available), 
but high precisions are likely to require a great amount of processing time. It is 
recommended that you use the default value whenever possible. 


controls the form of exponential notation for the result of arithmetic operations and 
built-in functions. This can be either SCIENTIFIC (in which case only one, nonzero 
digit appears before the decimal point) or ENGINEERING (in which case the power 
of 10 is always a multiple of 3). The default is SCIENTIFIC. The subkeywords 
SCIENTIFIC or ENGINEERING must be specified as symbols. The package value 
can be retrieved using the Package class form method. 


controls how many digits, at full precision, are ignored during a numeric comparison 
operation. (See Numeric Comparisons.) The value fuzz must be a symbol or string 
that is a valid positive whole number value and must be smaller than the current 
DIGIT ::OPTIONS setting. The package value can be retrieved using the Package 
class fuzz method. 

NUMERIC FUZZ temporarily reduces the value of NUMERIC DIGITS by the 
NUMERIC FUZZ value during every numeric comparison. The numbers are 
subtracted under a precision of DIGITS minus FUZZ digits during the comparison 
and are then compared with 0. 


controls the tracing action (that is, how much is displayed to the user) during the 
processing of all Rexx code contained in the package. Tracing describes some or all 
of the clauses in a program, producing descriptions of clauses as they are processed. 
TRACE is mainly used for debugging. The value trace must be one of the Trace 
Alphabetic Character (Word) Options valid for the Trace instruction. The package 
value can be retrieved using the Package class trace method. 


3.6. ::REQUIRES 


The ::REQUIRES directive specifies that the program requires access to the classes and objects of the 


Rexx program programname. 


2»2-::REQUIRES--"programname"--4--------- Фа << eene em eee >< 


+-LIBRARY-+ 


If the LIBRARY option is not specified, all public classes and routines defined in the named program are 
made available to the executing program. The programname is a literal string or a symbol that is taken as 


а constant. The string or symbol programname can be any string or symbol that is valid as the target of a 


CALL instruction. The program programname is called as an external routine with no arguments. The 


program is searched for using normal external program search order. See Search Order for details. The 


main program code, which precedes the first directive instruction, is run. 
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If any Rexx code preceeds the first directive in programname then that code is executed at the time the 
“REQUIRES is processed by the interpreter. This will be executed prior to executing the main Rexx 
program in the file that specifies the :: REQUIRES statement. 


If the LIBRARY option is specified, programname is the name of an external native library that is 
required by this program. The library will be loaded using platform-specific mechanisms, which 
generally means the library name is case sensitive. Any routines defined in the library will be made 
available to all programs running in the process. If the native library cannot be loaded, the program will 
not be permitted to run. All LIBRARY ::REQUIRES directives will be processed before ::REQUIRES 
for Rexx programs, which will ensure that the native libraries are available to the initialization code of 
the Rexx packages. 


:z REQUIRES directives can be placed anywhere after the main section of code in the package. The order 
of :: REQUIRES directives determines the search order for classes and routines defined in the named 
programs and also the load order of the referenced files. Once a program is loaded by а ::REQUIRES 
statement in a program, other references to that same program by ::REQUIRES statements in other 
programs will resolve to the previously loaded program. The initialization code for the ::REQUIRES file 
will only be executed on the first reference. 


The following example illustrates that two programs, ProgramA and ProgramB, can both access classes 
and routines that another program, ProgramC, contains. (The code at the beginning of ProgramC runs 
prior to the start of the main Rexx program.) 


/* ProgramA /* ProgramB 


'Programc' ires 'ProgramC' 


/* ProgramC 





The language processor uses local routine definitions within a program in preference to routines of the 
same name accessed through ::REQUIRES directives. Local class definitions within a program override 
classes of the same name in other programs accessed through ::REQUIRES directives. 


Another directive, or the end of the program, must follow a ::REQUIRES directive. Only null clauses can 
appear between them. 
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3.7. ::ROUTINE 


The ::ROUTINE directive creates named routines within a program. 


+-PRIVATE-+ 
>>-: :ROUTINE--rout inename--+--------- а= pz >< 
+-PUBLIC--+ +-EXTERNAL-spec-+ 


The routinename is a literal string or a symbol that is taken as a constant. Only one ::ROUTINE directive 
can appear for any routinename in a program. 


If the EXTERNAL option is not specified, the :: ROUTINE directive starts a routine, which is ended by 
another directive or the end of the program. 


If you specify the PUBLIC option, the routine is visible beyond its containing Rexx program to any other 
program that references this program with a :: REQUIRES directive. If you do not specify the PUBLIC 
option, the routine is visible only within its containing Rexx program. 


Routines you define with the ::ROUTINE directive behave like external routines. In the search order for 
routines, they follow internal routines and built-in functions but precede all other external routines. 


Example: 


::class c 
::method a 
call r "A" /* displays "In method A" */ 


: :method b 
call r "B" /* displays "In method B" */ 


::routine г 
use arg name 
say "In method" name 


If the EXTERNAL option is specified, then spec identifies a routine in an external native library that will 
be defined as the named routine for this program. The spec is a literal string containing a series of 
whitespace delimited tokens defining the external function. The first token identifies the type of native 
routine to locate: 


LIBRARY 


Identifies a routine in an external native library of the type supported by the ::REQUIRES directive. 
The second token must identify the name of the external library. The external library is located 
using platform-specific mechanisms for loading libraries. For Unix-based systems, the library name 
is case-sensitive. The third token is optional and specifies the name of the routine within the library 
package. If not specified, the :: ROUTINE name is used. The routine name is not case sensitive. 


REGISTERED 


Identifies a routine in an older-style Rexx function package. The second token must identify the 
name of the external library. The external library is located using platform-specific mechanisms for 
loading libraries. For Unix-based systems, the library name is case-sensitive. The third token is 
optional and specifies the name of the function within the library package. If not specified, the 
zROUTINE name is used. Loading of the function will be attempted using Ше name as given and as 
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all uppercase. Using REGISTERED is the equivalent of loading an external function using the 
RXFUNCADDO(O built-in function. See . METHODS for more details. 


Example: 


-- load a function from rxmath library 

::routine RxCalcPi EXTERNAL "LIBRARY rxmath" 

-- same function, but a diffent internal name 

::routine Pi EXTERNAL "LIBRARY rxmath RxCalcPi" 

-- same as call rxfuncadd "SQLLoadFuncs", "rexxsql", "SQLLoadFuncs" 
::routine SQLLoadFuncs "REGISTERED rexxsql SQLLoadFuncs" 


Notes: 


1. It is an error to specify :: ROUTINE with the same routine name more than once in the same 
program. It is not an error to have a local :: ROUTINE with the same name as another :: ROUTINE in 
another program that the :: REQUIRES directive accesses. The language processor uses the local 
: ROUTINE definition in this case. 


2. Calling an external Rexx program as a function is similar to calling an internal routine. For an 
external routine, however, the caller's variables are hidden and the internal values (NUMERIC 
settings, for example) start with their defaults. 


Note: If you specify the same ::ROUTINE routinename more than once in different programs, the last 
one is used. Using more than one :: ROUTINE routinename in the same program produces an error. 
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This chapter provides an overview of the Rexx class structure. 


A Rexx object consists of object methods and object variables ("attributes"). Sending a message to an 
object causes the object to perform some action; a method whose name matches the message name 
defines the action that is performed. Only an object’s methods can access the object variables belonging 
to an object. EXPOSE instructions within an object’s methods specify which object variables the 
methods will use. Any variables not exposed are local to the method and are dropped on return from a 
method. 


You can create an object by sending a message to а class object—typically a "new" method. An object 
created from a class is an instance of that class. The methods a class defines for its instances are called 
the instance methods of that class. These are the object methods that are available for every instance of 
the class. Classes can also define class methods, which are a class's own object methods. 


Note: When referring to instance methods (for objects other than classes) or class methods (for 
classes), this book uses the term methods when the meaning is clear from the context. When 
referring to instance methods and class methods of classes, this book uses the qualified terms to 
avoid possible confusion. 


4.1. Types of Classes 


There are four kinds of classes: 


* Object classes 
* Mixin classes 
* Abstract classes 
* Metaclasses 


The following sections explain these. 


4.1.1. Object Classes 


An object class is a factory for producing objects. An object class creates objects (instances) and 
provides methods that these objects can use. An object acquires the instance methods of the class to 
which it belongs at the time of its creation. If a class gains additional methods, objects created before the 
definition of these methods do not acquire the new or changed methods. 


The instance variables within an object are created on demand whenever a method EXPOSEs an object 
variable. The class creates the object instance, defines the methods the object has, and the object instance 
completes the job of constructing the object. 


The String class and the Array Class are examples of object classes. 
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4.1.2. Mixin Classes 


Classes can inherit from more than the single superclass from which they were created. This is called 
multiple inheritance. Classes designed to add a set of instance and class methods to other classes are 
called mixin classes, or simply mixins. 


You can add mixin methods to an existing class by sending an INHERIT message or using the INHERIT 
option on the ::CLASS directive. In either case, the class to be inherited must be a mixin. During both 
class creation and multiple inheritance, subclasses inherit both class and instance methods from their 
superclasses. 


Mixins are always associated with a base class, which is the mixin’s first non-mixin superclass. Any 
subclass of the mixin’s base class can (directly or indirectly) inherit a mixin; other classes cannot. For 
example, a mixin class created as a subclass of the Array class can only be inherited by other Array 
subclasses. Mixins that use the Object class as a base class can be inherited by any class. 


To create a new mixin class, you send a MIXINCLASS message to an existing class or use the ::CLASS 
directive with the MIXINCLASS option. A mixin class is also an object class and can create instances of 
the class. 


4.1.3. Abstract Classes 


Abstract classes provide definitions for instance methods and class methods but are not intended to 
create instances. Abstract classes often define the message interfaces that subclasses should implement. 


You create an abstract class like object or mixin classes. No extra messages or keywords on the ::CLASS 
directive are necessary. Rexx does not prevent users from creating instances of abstract classes. It is 
possible to create abstract methods оп a class. An abstract method is a placeholder that subclasses are 
expected to override. Failing to provide a real method implementation will result in an error when the 
abstract version is called. 


4.1.4. Metaclasses 


A metaclass is a class you can use to create another class. The only metaclass that Rexx provides is 
Class, the Class class. The Class class is the metaclass of all the classes Rexx provides. This means that 
instances of .Class are themselves classes. The Class class is like a factory for producing the factories 
that produce objects. 


To change the behavior of an object that is an instance, you generally use subclassing. For example, you 
can create Statarray, a subclass of the Array class. The statArray class can include a method for 
computing a total of all the numeric elements of an array. 


/* Creating an array subclass for statistics */ 

::class statArray subclass array public 

::method init /* Initialize running total and forward to superclass */ 
expose total 


total = 0 
/* init describes the init method. ж/ 
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::method put /* Modify to increment running total */ 
expose total 
use arg value 
total = total + value /* Should verify that value is numeric!!! */ 
forward class (super) 


::method "[]-" /* Modify to increment running total */ 
forward message "PUT" 


::imethod remove /* Modify to decrement running total */ 
expose total 
use arg index 
forward message "AT" continue 
total = total - result 
forward class (super) 


::method average /* Return the average of the array elements */ 
expose total 
return total / self^items 


::method total /* Return the running total of the array elements */ 
expose total 
return total 


You can use this method on the individual array instances, so it is an instance method. 


However, if you want to change the behavior of the factory producing the arrays, you need a new class 
method. One way to do this is to use the :: METHOD directive with the CLASS option. Another way to 
add a class method is to create a new metaclass that changes the behavior of the Statarray class. A new 
metaclass is a subclass of .class. 


You can use a metaclass by specifying it in a SUBCLASS or MIXINCLASS message or on a ::CLASS 
directive with the METACLASS option. 


If you are adding a highly specialized class method useful only for a particular class, use the :: METHOD 
directive with the CLASS option. However, if you are adding a class method that would be useful for 
many classes, such as an instance counter that counts how many instances a class creates, you use a 
metaclass. 


The following examples add a class method that keeps a running total of instances created. The first 
version uses the :: METHOD directive with the CLASS option. The second version uses a metaclass. 


Version 1 


/* Adding a class method using ::METHOD */ 


a 7 .point^new(1,1) /* Create some point instances ж/ 
say "Created point instance" a 
b 7 .point^new(2,2) /* create another point instance */ 
say "Created point instance" b 
c = .point^new(3,3) /* create another point instance */ 
say "Created point instance" c 

/* ask the point class how many */ 
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/* instances it has created 


say "The point class has created" .point^instances "instances." 


::class point public 


::method init class 
expose instanceCount 
instanceCount = 0 
forward class (super) 


::method new class 
expose instanceCount 
instanceCount = instanceCount + 1 
forward class (super) 


::method instances class 
expose instanceCount 
return instanceCount 


::method init 
expose xVal yVal 
use arg xVal, yVal 


::method string 
expose xVal yVal 


return "("xVal","yVal")" 


Version 2 


/ж 


/ж 
/ж 


/ж 
/ж 
/ж 


/ж 


/ж 


/ж 


/ж 
/ж 


create Point class 


Initialize instanceCount 


*/ 


*/ 


Forward INIT to superclass ж/ 


Creating a new instance 
Bump the count 
Forward NEW to superclass 


Return the instance count 


Set object variables 


as passed on NEW 


Use object variables 
to return string value 


/* Adding a class method using a metaclass ж/ 


a 7 .point^new(1,1) 
say "Created point instance" a 
b = .point^new(2,2) 
say "Created point instance" b 
c = .point^new(3,3) 
say "Created point instance" c 


*/ 
*/ 
*/ 


*/ 


*/ 


*/ 


*/ 
*/ 


/* Create some point instances ж/ 


/* ask the point class how many */ 


/* instances it has created ж/ 


say "The point class has created" .point^instances "instances." 


::class InstanceCounter subclass class /* Create a new metaclass 


::method init 
expose instanceCount 
instanceCount = 0 
forward class (super) 


::method new 
expose instanceCount 


that */ 
/* will count its instances ж/ 
/* Initialize instanceCount ж/ 


/* Forward INIT to superclass ж/ 


/* Creating a new instance */ 
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instanceCount = instanceCount + 1 /* Bump the count ж/ 
forward class (super) /* Forward NEW to superclass ж/ 


::method instances 
expose instanceCount /* Return the instance count ж/ 
return instanceCount 


:class point public metaclass InstanceCounter /ж Create Point class ж/ 
/* using InstanceCounter metaclass */ 
::method init 
expose xVal yVal /* Set object variables ж/ 
use arg xVal, yVal /* as passed on NEW ж/ 


::method string 
expose xVal yVal /* Use object variables ж/ 
return "("xVal","yVal")" /* to return string value */ 


4.2. Creating and Using Classes and Methods 


You can define a class using either directives or messages. 

To define a class using directives, you place a ::CLASS directive after the main part of your source 
program: 

::class "Account" 

This creates an Account class that is a subclass of the Object class. Object is the default superclass if one 
is not specified. (See The Object Class for a description of the Object class.) The string "Account" is a 


string identifier for the new class. The string identifier is both the internal class name and the name of the 
environment symbol used to locate your new class instance. 


Now you can use :: METHOD directives to add methods to your new class. The :: METHOD directives 
must immediately follow the ::CLASS directive that creates the class. 


::method type 
return "an account" 


::method "name=" 
expose name 
use arg name 


::method name 
expose name 


return name 


This adds the methods TYPE, NAME, and NAME= to the Account class. 


You can create a subclass of the Account class and define a method for it: 


::class "Savings" subclass account 
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::method type 
return "a savings account" 


Now you can create an instance of the Savings class with the NEW method (see NEW) and send TYPE, 
NAME, and NAME- messages to that instance: 


asav = .savings^new 
say asav type 
asav^name = "John Smith" 


The Account class methods NAME and NAME- create a pair of access methods to the account object 
variable NAME. The following directive sequence creates the NAME and NAME= methods: 


::method "name=" 
expose name 
use arg name 


::method name 
expose name 
return name 


You can replace this with a single ::ATTRIBUTE directive. For example, the directive 


::attribute name 


adds two methods, NAME and NAME- to a class. These methods perform the same function as the 
NAME and NAME= methods in the original example. The NAME method returns the current value of 
the object variable NAME; the NAME= method assigns a new value to the object variable NAME. 


In addition to defining operational methods and attribute methods, you can add "constant" methods to a 
class using Ше :: CONSTANT directive. The :: CONSTANT directive will create both a class method and 
an instance method to the class definition. The constant method will always return the same constant 
value, and can be invoked by sending a message to either the class or an instance method. For example, 
you might add the following constant to your Account class: 


::constant checkingMinimum 200 


This value can be retrieved using either of the following methods 


say .Account^checkingMinimum -- displays "200" 
asave = .savings^new 
say asave^checkingMinimum -- also displays "200" 


4.2.1. Using Classes 


When you create a new class, it is always a subclass of an existing class. You can create new classes with 
the ::CLASS directive or by sending the SUBCLASS or MIXINCLASS message to an existing class. If 
you specify neither the SUBCLASS nor the MIXINCLASS option on the ::CLASS directive, the 
superclass for the new class is the Object class, and it is not a mixin class. 


Example of creating a new class using a message: 


persistence = .object^mixinclass("Persistence") 
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myarray=.array~ subclass("myarray") ~~ inherit (persistence) 
Example of creating a new class using the directive: 


::class persistence mixinclass object 
::class myarray subclass array inherit persistence 


4.2.2. Scope 


A scope refers to the methods and object variables defined for a single class (not including the 
superclasses). Only methods defined in a particular scope can access the object variables within that 
scope. This means that object variables in a subclass can have the same names as object variables used 
by a superclass, because the variables are created at different scopes. 


4.2.3. Defining Instance Methods with SETMETHOD or 
ENHANCED 


In Rexx, methods are usually associated with instances using classes, but it is also possible to add 
methods directly to an instance using the SETMETHOD (see SETMETHOD) or ENHANCED (see 
ENHANCED) method. 


All subclasses of the Object class inherit SETMETHOD. You can use SETMETHOD to create one-off 
objects, objects that must be absolutely unique so that a class that is capable of creating other instances is 
not necessary. The Class class also provides an ENHANCED method that lets you create new instances 
of a class with additional methods. The methods and the object variables defined on an object with 
SETMETHOD or ENHANCED form a separate scope, like the scopes the class hierarchy defines. 


4.2.4. Method Names 


A method name can be any string. When an object receives a message, the language processor searches 
for a method whose name matches the message name in uppercase. 


Note: The language processor also translates the specified name of all methods added to objects 
into uppercase characters. 


You must surround a method name with quotation marks when it contains characters that are not allowed 
in a symbol (for example, the operator characters). The following example creates a new class (the Cost 
class), defines a new method (96), creates an instance of the Cost class (mycost), and sends а % message 
to mycost: 


cost-.object^subclass("A cost") 
cost^define("4", 'expose p; say "Enter a price."; pull p; say p*1.07;') 
mycost-cost^new 
mycost^ "4" /* Produces: Enter a price. ж/ 
/* If the user specifies а price of 100, ж/ 


ooRexx Reference Version 4.0.0 99 


Chapter 4. Objects and Classes 


/* produces: 107.00 ж/ 


4.2.5. Default Search Order for Method Selection 


The search order for a method name matching the message is for: 


1. A method the object itself defines with SETMETHOD or ENHANCED. (See SETMETHOD .) 


2. A method the object’s class defines. (Note that an object acquires the instance methods of the class 
to which it belongs at the time of its creation. If a class gains additional methods, objects created 
before the definition of these methods do not acquire these methods.) 


3. A method that a superclass of the object’s class defines. This is also limited to methods that were 
available when the object was created. The order of the INHERIT (see INHERIT) messages sent to 
an object’s class determines the search order of the superclass method definitions. 


This search order places methods of a class before methods of its superclasses so that a class can 
supplement or override inherited methods. 


If the language processor does not find a match for the message name, the language processor checks the 
object for a method name UNKNOWN. If it exists, the language processor calls the UNKNOWN method 
and returns as the message result any result the UNKNOWN method returns. The UNKNOWN method 
arguments are the original message name and a Rexx array containing the original message arguments. 


If the object does not have an UNKNOWN method, the language processor raises a NOMETHOD 
condition. If there are no active traps for the NOMETHOD condition, a syntax error is raised. 


4.2.6. Defining an UNKNOWN Method 


When an object that receives a message does not have a matching message name, the language processor 
checks if the object has a method named UNKNOWN. If the object has an UNKNOWN method, the 
language processor calls UNKNOWN, passing two arguments. The first argument is the name of the 
method that was not located. The second argument is an array containing the arguments passed with the 
original message. 


For example, the following UNKNOWN method will print out the name of the invoked method and then 


invoke the same method on another object. This can be used track the messages that are sent to an object: 


::method unknown 

expose target -- will receive all of the messages 

use arg name, arguments 

say name "invoked with" arguments toString 

forward to(target) -- send along the message with the original args 


4.2.7. Changing the Search Order for Methods 


You can change the usual search order for methods by: 
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1. Ensuring that the receiver object is the sender object. (You usually do this by specifying the special 
variable SELF. 


N 


. Specifying a colon and a class symbol after the message name. The class symbol can be a variable 
name or an environment symbol. It identifies the class object to be used as the starting point for the 
method search. 


The class object must be a superclass of the class defining the active method, or, if you used 
SETMETHOD to define the active method, the object’s own class. The class symbol is usually the 
special variable SUPER (see SUPER) but it can be any environment symbol or variable name whose 
value is a valid class. 


Suppose you create an Account class that is a subclass of the Object class, define a TYPE method for the 
Account class, and create the Savings class that is a subclass of Account. You could define a TYPE 
method for the Savings class as follows: 


savings^define("TYPE", 'return "a savings account"') 
You could change the search order by using the following line: 
savings^define("TYPE", 'return self^type:super "(savings)"') 


This changes the search order so that the language processor searches for the TYPE method first in the 
Account superclass (rather than in the Savings subclass). When you create an instance of the Savings 
class (asav) and send a TYPE message to asav: 


say asav type 


an account (savings) is displayed. The TYPE method of the Savings class calls the TYPE method of 
the Account class, and adds the string (savings) to the results. 


4.2.8. Public and Private Methods 


A method can be public or private. Any object can send a message that runs a public method. A private 
method can only be invoked from specific calling contexts. These contexts are: 


1. From within a method owned by the same class as the target. This is frequently the same object, 
accessed via the special variable SELF. Private methods of an object can also be accessed from other 
instances of the same class (or subclass instances). 


2. From within a method defined at the same class scope as the method. For example: 


::class Savings 

::method newCheckingAccount CLASS 
instance = self^new 
instance” makeChecking 
return instance 


::method makeChecking private 


expose checking 
checking = .true 
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The newCheckingAccount CLASS method is able to invoke the makeChecking method because the 
scope of the makeChecking method is .Savings. 


3. From within an instance (or subclass instance) of a class to a private class method of its class. For 
example: 
::class Savings 
::method init class 


expose counter 
counter - 0 


::method allocateAccountNumber private class 
expose counter 
counter - counter * 1 
return counter 


::method init 
expose accountNumber 
accountNumber = self^class^allocateAccountNumber 


The instance init method of the Savings class is able to invoke the allocateAccountNumber private 
method of the .Savings class object because it is owned by an instance of the .Savings class. 


Private methods include methods at different scopes within the same object. This allows superclasses to 
make methods available to their subclasses while hiding those methods from other objects. A private 
method is like an internal subroutine. It shields the internal information of an object to outsiders, but 
allowing objects to share information with each other and their defining classes. 


4.2.9. Initialization 


Any object requiring initialization at creation time must define an INIT method. If this method is defined, 
the class object runs the INIT method after the object is created. If an object has more than one INIT 
method (for example, it is defined in several classes), each INIT method must forward the INIT message 
up the hierarchy to complete the object's initialization. 


Example: 
asav = .savings^new(1000.00, 6.25) 
say asav type 
asav^name = "John Smith" 
::class Account 
::method INIT 
expose balance 


use arg balance 


::method TYPE 
return "an account" 


::method name attribute 


::class Savings subclass Account 
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::method INIT 
expose interest rate 
use arg balance, interest rate 
self^init:super(balance) 


::method type 
return "a savings account" 


The NEW method of the Savings class object creates a new Savings object and calls the INIT method of 
the new object. The INIT method arguments are the arguments specified on the NEW method. In the 
Savings INIT method, the line: 


self^init:super(balance) 


calls the INIT method of the Account class, using just the balance argument specified on the NEW 
message. 


4.2.10. Object Destruction and Uninitialization 


Object destruction is implicit. When an object is no longer in use, Rexx automatically reclaims its 
storage. If the object has allocated other system resources, you must release them at this time. (Rexx 
cannot release these resources, because it is unaware that the object has allocated them.) 


Similarly, other uninitialization processing may be needed, for example, by a message object holding an 
unreported error. An object requiring uninitialization should define an UNINIT method. If this method is 
defined, Rexx runs it before reclaiming the object's storage. If an object has more than one UNINIT 
method (defined in several classes), each UNINIT method is responsible for sending the UNINIT 
method up the object hierarchy. 


4.2.11. Required String Values 


Rexx requires a string value in a number of contexts within instructions and built-in function calls. 


* DO statements containing exprr or exprf 

* Substituted values in compound variable names 

* Commands to external environments 

* Commands and environment names on ADDRESS instructions 

* Strings for ARG, PARSE, and PULL instructions to be parsed 

* Parenthesized targets on CALL instructions 

* Subsidiary variable lists on DROP, EXPOSE, and PROCEDURE instructions 
* Instruction strings on INTERPRET instructions 

* DIGITS, FORM, and FUZZ values on NUMERIC instructions 


* Options strings on OPTIONS instructions 
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* Data queue strings on PUSH and QUEUE instructions 

* Label names on SIGNAL VALUE instructions 

* Trace settings on TRACE VALUE instructions 

* Arguments to built-in functions 

* Variable references in parsing templates 

* Data for PUSH and QUEUE instructions to be processed 

* Data for the SAY instruction to be displayed 

* Rexx dyadic operators when the receiving object (the object to the left of the operator) is a string 


If you supply an object other than a string in these contexts, by default the language processor converts it 
to some string representation and uses this. However, the programmer can cause the language processor 
to raise the NOSTRING condition when the supplied object does not have an equivalent string value. 


To obtain a string value, the language processor sends a REQUEST( STRING") message to the object. 
Strings and other objects that have string values return the appropriate string value for Rexx to use. (This 
happens automatically for strings and for subclasses of the String class because they inherit a suitable 
MAKESTRING method from the String class.) For this mechanism to work correctly, you must provide 
a MAKESTRING method for any other objects with string values. 


For other objects without string values (that is, without a MAKESTRING method), the action taken 
depends on the setting of the NOSTRING condition trap. If the NOSTRING condition is being trapped 
(see Conditions and Condition Traps), the language processor raises the NOSTRING condition. If the 
NOSTRING condition is not being trapped, the language processor sends a STRING message to the 
object to obtain its readable string representation (see the STRING method of the Object class STRING) 
and uses this string. 


When comparing a string object with the Nil object, if the NOSTRING condition is being trapped, then 
if string - .nil 
will raise the NOSTRING condition, whereas 


if .nil - string 


% та" 


will not as the Nil object’s method does not expect a string as an argument. 


Example: 


d = .directory^new 

say substr(d,5,7) /* Produces "rectory" from "a Directory" */ 
signal on nostring 

say substr(d,5,7) /* Raises the NOSTRING condition */ 

say substr(d^string,3,6) /ж Displays "Direct" */ 


For arguments to Rexx object methods, different rules apply. When a method expects a string as an 
argument, the argument object is sent the REQUEST(' STRING") message. If REQUEST returns the Nil 
object, then the method raises an error. 
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4.2.12. Concurrency 


Rexx supports concurrency, multiple methods running simultaneously on a single object. See 
Concurrency for a full description of concurrency. 


4.3. Overview of Classes Provided by Rexx 


This section gives a brief overview of the classes and methods Rexx defines. 


4.3.1. The Class Hierarchy 


Rexx provides the following classes belonging to the object class: 


* Alarm class 
* Array class 
* Class class 
* Collection class 
- MapCollection class 
* OrderedCollection class 


• SetCollection class 


* Comparable class 
* Orderable class 
* Comparator class 
+ CaselessColumnComparator class 
+ CaselessComparator class 
+ CaselessDescendingComparator class 
- ColumnComparator class 
. DescendingComparator class 


. InvertingComparator class 
* DateTime class 
* Directory class 


e Properties class 


* InputOutputStream class 
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* Stream class 


* InputStream class 

* List class 

* Message class 

* Method class 

* Method class 

* Routine class 

* MutableBuffer class 
* OutputStream class 
* Queue class 


* CircularQueue class 


* RegularExpression class 
* Relation class 


. Bag class 


* RexxQueue class 
* Stem class 

* String class 

* Supplier class 


. StreamSupplier class 


* Table class 


. Setclass 


* IdentityTable class 

* TimeSpan class 

* WeakReference class 

* RexxContext class 

* Buffer class 

* Pointer class 

(The classes are in a class hierarchy with subclasses indented below their superclasses.) 


Note that there might also be other classes in the system, depending on the operating system. Additional 
classes may be accessed by using an appropriate ::requires directive to load the class definitions. 
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The following figures show Rexx built-in classes. 


Figure 4-1. Classes and Inheritance (part 1 of 9) 

















Figure 4-2. Classes and Inheritance (part 2 of 9) 
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Figure 4-3. Classes and Inheritance (part 3 of 9) 
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Figure 4-4. Classes and Inheritance (part 4 of 9) 
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Figure 4-5. Classes and Inheritance (part 5 of 9) 
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Figure 4-6. Classes and Inheritance (part 6 of 9) 
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Figure 4-7. Classes and Inheritance (part 7 of 9) 
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Figure 4-8. Classes and Inheritance (part 8 of 9) 
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Figure 4-9. Classes and Inheritance (part 9 of 9) 





Object 


4.3.2. Class Library Notes 


The chapters that follow describe the classes and other objects that Rexx provides and their available 
methods. Rexx provides the objects listed in these sections and they are generally available to all 
methods through environment symbols (see Environment Symbols). 


Notes: 


1. In the method descriptions in the chapters that follow, methods that return a result begin with the 
word "returns". 


N 


. For [] and []= methods, the syntax diagrams include the index or indexes within the brackets. These 
diagrams are intended to show how you can use these methods. For example, to retrieve the first 
element of a one-dimensional array named Array1, you would typically use the syntax: 


Array1[1] 
rather than: 


Arrayi^"[]"(1) 
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even though the latter is valid and equivalent. For more information, see Message Terms and 
Message Instructions. 


3. When the argument of a method must be a specific kind of object (such as array, class, method, or 
string) the variable you specify must be of the same class as the required object or be able to produce 
an object of the required kind in response to a conversion message. In particular, subclasses are 
acceptable in place of superclasses (unless overridden in a way that changes superclass behavior), 
because they inherit a suitable conversion method from their Rexx superclass. 


The isA method of the Object class can perform this validation. 
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This chapter describes all of the Rexx built-in classes. 


Fundamental Classes 
This set of classes are the fundamental building blocks for all other classes. It includes the Object 
class, the Class class, the String class, the Method class, and the Routine class, and the Package 
class, and the Message class. 

Stream Classes 
This set of classes implement the classic Rexx streams. It includes the Stream class, the 
InputStream class, the OutputStream class, and the InputOutputStream class. 

Collection Classes 


This set of classes implement object collections. It includes the Directory class, the Properties class, 
the Relation class, the Stem class, the Table class, the IdentityTable class, the Array class, the List 
class, the Queue class, the CircularQueue class, the Bag class, and the Set class. 


Utility Classes 


This set of classes are utility in nature and hard to classify. It includes the Alarm class, the 
Comparable class, the Comparator class, the Orderable class, the DateTime class, the 
MutableBuffer class, the RegularExpression class, the RexxContext class, the RexxQueue class, the 
StreamSupplier class, the Supplier class, the TimeSpan class and the WeakReference class. 


5.1. The Fundamental Classes 


This section describes the Rexx fundamental classes. 


5.1.1. The Object Class 


The Object class is the root of the class hierarchy. The instance methods of the Object class are, 
therefore, available on all objects. 
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Figure 5-1. The Object class and methods 
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Note: The Object class also has available class methods that its metaclass, the Class class, defines. 


5.1.1.1. new (Class Method) 


Returns a new instance of the receiver class. 
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5.1.1.2. Operator Methods 


>>-comparison_operator (argument)------------------------------- >< 


Returns 1 (true) or 0 (false), the result of performing a specified comparison operation. 


For the Object class, if argument is the same object as the receiver object, the result is 1 (true), otherwise 
0 (false) is returned. Subclasses may override this method to define equality using different criteria. For 
example, the String class determines equality based on the value of the string data. 


Note: The MapCollection classes such as Table and Relation use the == operator combined with the 
hashCode method to determine index and item equivalence. It is generally necessary for a class to 
override both the hashCode method and the == operator method to maintain the contract specified 
for the hashCode method. See hashCode Method for details on the contract. 


The comparison operators you can use in a message are: 


True if the terms are the same object. 


\=, ><, <>, \== 


True if the terms are not the same object (inverse of =). 


5.1.1.3. Concatenation Methods 


»»-concatenation operator(argument)---------------------------- >< 


Returns a new string that is the concatenation the of receiver object’s string value with argument. (See 
String Concatenation.) The concatenation_operator can be: 


пи 


concatenates without an intervening blank. The abuttal operator "" is the null string. The language 


processor uses the abuttal operator to concatenate two terms that another operator does not separate. 


concatenates without an intervening blank. 
"ow 


"on 


concatenates with one blank between the receiver object and the argument. (The operator " " is a 
blank.) 


5.1.1.4. class 


>>-павв---------в6-----#----- <<< RRS SSSR SSS rere acere >< 
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Returns the class object that created the object instance. 


5.1.1.5. copy 


Returns a copy of the receiver object. The copied object has the same methods as the receiver object and 
an equivalent set of object variables, with the same values. 


Example: 
myarray-.array^of("N","S","E","W") 


/* Copies array myarray to array directions */ 
directions-myarray^ сору 


Note: The copy method is a "shallow copy". Only the target object is copied. Additional objects 
referenced by the target object are not copied. For example, copying an Array object instance only 
copies the array, it does not copy any of the objects stored in the array. 


5.1.1.6. defaultName 
22-defaultNamé--------——--—-—-—----ccc Sess SSS SSS Sasa SS SSeS == >< 


Returns a short human-readable string representation of the object. The exact form of this representation 
depends on the object and might not alone be sufficient to reconstruct the object. All objects must be able 
to produce a short string representation of themselves in this way, even if the object does not have a 
string value. See Required String Values for more information. The defaultName method of the Object 
class returns a string that identifies the class of the object, for example, an Array or a Directory. See also 
objectName and string. See objectName= for an example using defaultName. 


5.1.1.7. hashCode 


22-hashCode------4—-—--———- oen SSS SSSR SSeS SRS --- >< 
Returns a string value that is used as a hash value for MapCollections such as Table, Relation, Set, Bag, 
and Directory. MapCollections use this string value to hash an object for hash table-based searches. 


Object implementations are expected to abide by a general contract for hash code usage: 


* Whenever hashCode is invoked on the same object more than once, hashCode must return the same 
hashcode value, provided than none of the internal information the object uses for ап "==" comparison 
has changed. 


* If two object instances compare equal using the "==" operator, the hashCode methods for both object 
instances must return the same value. 
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* Itis not required that two object instances that compare unequal using "==" return different hash code 
values. 


* Returning a wide range of hash values will produce better performance when an object is used as an 
index for a MapCollection. A return value of 4 string characters is recommended. The characters in 
the hash value may be any characters from ’00’x to ’ff’x, inclusive. 


5.1.1.8. hasMethod 


»»-hasMethod (methodname)--------------------------------------- >< 


Returns 1 (true) if the receiver object has a method named methodname (translated to uppercase). 
Otherwise, it returns 0 (false). 


Note: The hasMethod object will return true even if the target method is defined as private. A private 
method has restricted access rules, so its possible to receive an unknown method error (error 97) 
when invoking methodname even if hasMethod indicates the method exists. See Public versus 
Private Methods for private method restrictions. 


5.1.1.9. identityHash 


>2-двешфуНазн-------------------------------- ---- >< 


Returns a unique identity number for Ше object. This number is guaranteed to be unique for Ше receiver 
object until the object is garbage collected. 


5.1.1.10. init 


>>-іпі%-------------------------------------------------------- >< 


Performs апу required object initialization. Subclasses of the Object class сап override this method to 
provide more specific initialization. 


5.1.1.11. instanceMethod 


>>-instanceMethod (methodname)---------------------------------- >< 


Returns the corresponting Method class instance if the methodname is a valid method of the class. 
Otherwise it returns the Nil object. 


5.1.1.12. instanceMethods 


>>-instanceMethods (class)---------------------------------- >< 
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Returns a Supplier instance containing the names and corresponding method objects defined by class. If 
the receiver object is not an instance of class, the Nil object is returned. 


5.1.1.13. isA 


»»-isA(class)-------------------------------------------------- >< 


Note: This method is an alias of the isInstanceOf method. 


5.1.1.14. isInstanceOf 


>>-isInstanceDf (class)----------------------------------------- >< 


Returns .true ("1") if the object is an instance of the specified class, otherwise it returns .false ("0"), An 
object is an instance of a class if the object is directly an instance of the specified class or if class is in 
the object’s direct or mixin class inheritance chain. For example: 


"abc"~isInstanceDf (.string) -> 1 
"abc"~isInstanceDf (.object) -> 1 
"abc"~isInstanceOf (.mutablebuffer) -> 0 


5.1.1.15. objectName 


>>-орцес Маше---------------<-----.-а------------------------ >< 


Returns апу name set оп the receiver object using the objectName= method. If the receiver object does 
not have a name, this method returns the result of the defaultName method. See Required String Values 
for more information. See the objectName= method for an example using objectName. 


5.1.1.16. objectName= 


>>-objectName=(newname) ---------------------------------------- >< 


Sets the receiver object’s name to the string newname. 


Example: 


points=. array^of ("N" ; "gn y "Е" 3 пу") 


say points~objectName /* (mo change yet) Says: "an Array" */ 
points^objectName-("compass") /* Changes obj name POINTS to "compass"*/ 
say points^objectName /* Shows new obj name. Says: "compass" */ 
say points^defaultName /* Default is still available. */ 

/* Says "an Array" */ 
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say points /* Says string representation of */ 
/* points "compass" */ 
say points[3] /* Says: "E"Points is still an array  */ 
/* of 4 items ж/ 


5.1.1.17. request 


»»-request(classid)-------------------------------------------- >< 


Returns an object of the classid class, or the Nil object if the request cannot be satisfied. 


This method first compares the identity of the object’s class (see the id method of the Class class in id) to 
classid. If they are the same, the receiver object is returned as the result. Otherwise, request tries to 
obtain and return an object satisfying classid by sending the receiver object the conversion message make 
with the string classid appended (converted to uppercase). For example, a request ("string") message 
causes a makeString message to be sent. If the object does not have the required conversion method, 
request returns the Nil object. 


The conversion methods cause objects to produce different representations of themselves. The presence 
or absence of a conversion method defines an object's capability to produce the corresponding 
representations. For example, lists can represent themselves as arrays, because they have a makeArray 
method, but they cannot represent themselves as directories, because they do not have a makeDirectory 
method. Any conversion method must return an object of the requested class. For example, makeArray 
must return an array. The language processor uses the makeString method to obtain string values in 
certain contexts; see Required String Values. 


5.1.1.18. run 


»»-run(method-4------------------------------- %-)-------------- >< 
| %--------------- + | 
| V | | 
*-,Individual---4----------- TL 
| +-,argument-+ | 
*-,Array,argument--------------- * 


Runs the method object method (see The Method Class). The method has access to the object variables 
of the receiver object, as if the receiver object had defined the method by using setMethod. 


If you specify the Individual or Array option, any remaining arguments are arguments for the method. 
(You need to specify only the first letter; all characters following the first character are ignored.) 


Individual 
Passes any remaining arguments to the method as arguments in the order you specify them. 


Array 


Requires argument, which is an array object. (See The Array Class.) The member items of the array 
are passed to the method as arguments. The first argument is at index 1, the second argument at 
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index 2, and so on. If you omitted any indexes when creating the array, the corresponding arguments 
are omitted when passing the arguments. 


If you specify neither Individual nor Array, the method runs without arguments. 


The method argument can be a string containing a method source line instead of a method object. 
Alternatively, you can pass an array of strings containing individual method lines. In either case, run 
creates an equivalent method object. 


Notes: 


1. The run method is a private method. See Public versus Private Methods for information private 
method restrictions. 


2. The RUN method is a protected method. 


5.1.1.19. send 


»»-send(messagename---4----------- *-—-)----------------------- >< 
*-,argument--* 


Returns a result of invoking a method on the target object using the specified messange name and 
arguments. The send() method allows methods to be invoked using dynamically constructed method 
names. 


The messagename can be a string or an array. If messagename is an array object, its first item is the name 
of the message and its second item is a class object to use as the starting point for the method search. For 
more information, see Classes and Inheritance. 


Any arguments are passed to the receiver as arguments for messagename in the order you specify them. 


Example: 


world-.WorldÜbject^new 

// the following 3 calls are equivalent 
msgi-world^hello("Fred") 

msg2-world^send("HELLO", "Fred") 
msg3-.message^new(world,"HELLO", "i", "Fred")^^send 


say msgi^result /* Produces Hello Fred 21:04:25.065000 ж/ 
/* for example ж/ 
say msg2~result /* Produces Hello Fred 21:04:25.081000 ж/ 
/* for example ж/ 
say msg3^ result /* Produces Hello Fred 21:04:25.101000 */ 
/* for example ж/ 


::class ’WorldObject’ public 
::method hello 

use arg name 

return "Hello" name time(?L?) 
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5.1.1.20. sendWith 


»»-sendWith(messagename,arguments)-------------------------------- >< 


Returns a result of invoking a method on the target object using the specified messange name and 
arguments. The send() method allows methods to be invoked using dynamically constructed method 
names and arguments. 


The messagename can be a string or an array. If messagename is an array object, its first item is the name 
of the message and its second item is a class object to use as the starting point for the method search. For 
more information, see Classes and Inheritance. 


The arguments argument must be a single-dimension array instance. The values contained in arguments 
are passed to the receiver as arguments for messagename in the order you specify them. 


Example: 


world=.WorldObject “new 

// the following 3 calls are equivalent 
msgi-world^hello("Fred") 

msg2-world^sendWith("HELLO", .array^of("Fred")) 
msg3-.message^new(world,"HELLO", "A", .array^of("Fred"))^^send 


say msgi^result /* Produces Hello Fred 21:04:25.065000 */ 
/* for example ж/ 
say msg2~result /* Produces Hello Fred 21:04:25.081000 ж/ 
/* for example ж/ 
say msg3~result /* Produces Hello Fred 21:04:25.101000 ж/ 
/* for example ж/ 


::class ’?WorldObject’ public 
::method hello 

use arg name 

return "Hello" name time(?L?) 


5.1.1.21. setMethod 


»»-setMethod(methodname-4---------------------- %--)----------------- >< 
| +-,"FLOAT"-+ | 
+-,method-+---------- +-+ 
%--,всоре--% 


Adds a method to the receiver object’s collection of object methods. The methodname is the name of the 
new method. This name is translated to uppercase. If you previously defined a method with the same 
name using setMethod, the new method replaces the earlier one. If you omit method, setMethod makes 
the method name methodname unavailable for the receiver object. In this case, sending a message of that 
name to the receiver object runs the unknown method (if any). 


The method can be a string containing a method source line instead of a method object. Or it can be an 
array of strings containing individual method lines. In either case, setMethod creates an equivalent 
method object. 
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The third parameter describes if the method that is attached to an object should have object or float 
scope. "Float" scope means that it shares the same scope with methods that were defined outside of a 
class. "Object" scope means it shares the scope with other, potentially statically defined, methods of the 
object it is attached to. 


Notes: 


1. The setMethod method is a private method. See the setPrivate method in setPrivate for details. 


2. The setMethod method is a protected method. 


5.1.1.22. start 


>>-start (messagename---4----------- %-%-)----------------------- >< 
+—-,argument-+ 


Returns a message object (see The Message Class) and sends it a start message to start concurrent 
processing. The object receiving the message messagename processes this message concurrently with the 
sender’s continued processing. 


The messagename can be a string or an array. If messagename is an array object, its first item is the name 
of the message and its second item is a class object to use as the starting point for the method search. For 
more information, see Classes and Inheritance. 


Any arguments are passed to the receiver as arguments for messagename in the order you specify them. 


When the receiver object has finished processing the message, the message object retains its result and 
holds it until the sender requests it by sending a result message. For further details, see start. 


Example: 
world=.WorldObject “new 


msgi-world^start ("HELLO") /* same as next line ж/ 
msg2-.message^new(world,"HELLO")^^start /* same as previous line */ 


say msgi~result /* Produces Hello world 21:04:25.065000 */ 
/* for example ж/ 
say msg2^result /* Produces Hello world 21:04:25.081000 */ 
/* for example ж/ 


::class ’?WorldObject’ public 
::method hello 
return "Hello world" time(’L’) 


5.1.1.23. startWith 


»»-startWith(messagename,arguments)-------------------------------- >< 
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Returns a message object (see The Message Class) and sends it a start message to start concurrent 
processing. The object receiving the message messagename processes this message concurrently with the 
sender’s continued processing. 


The messagename can be a string or an array. If messagename is an array object, its first item is the name 
of the message and its second item is a class object to use as the starting point for the method search. For 
more information, see Classes and Inheritance. 


The arguments argument must be a single-dimension array instance. Any values contained in arguments 
are passed to the receiver as arguments for messagename in the order you specify them. 


When the receiver object has finished processing the message, the message object retains its result and 
holds it until the sender requests it by sending a result message. For further details, see start. 


Example: 


world=.WorldObject “new 


msgi-world^startWith("HELLO", .array~of ("Fred") /* same as next line ж/ 
msg2-.message^new(world,"HELLO", і’, .array^of("Fred"))^^start /ж same as previous line ж/ 
say msgi^result /* Produces Hello Fred 21:04:25.065000 ж/ 

/* for example ж/ 
say msg2~result /* Produces Hello Fred 21:04:25.081000 ж/ 

/* for example ж/ 


::class ’?WorldObject’ public 
::method hello 

use arg name 

return "Hello" name time(’L’) 


5.1.1.24. string 
сеа б Ng ааа >< 


Returns a human-readable string representation of the object. The exact form of this representation 
depends on the object and might not alone be sufficient to reconstruct the object. All objects must be able 
to produce a string representation of themselves in this way. 


The object’s string representation is obtained from the objectName method (which can in turn use the 
defaultName method). See also the objectName method (OBJECTNAME) and the defaultName 
method (defaultName). 


The distinction between this method, the makeString method (which obtains string values—see 
makeString) and the request method (see request) is important. All objects have a string method, which 
returns a string representation (human-readable form) of the object. This form is useful in tracing and 
debugging. Only those objects that have information with a meaningful string form have a makeString 
method to return this value. For example, directory objects have a readable string representation (a 
Directory), but no string value, and, therefore, no makeString method. 


Of the classes that Rexx provides, only the String class has a makeString method. Any subclasses of the 
String class inherit this method by default, so these subclasses also have string values. Any other class 
can also provide a string value by defining a makeString method. 
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5.1.1.25. unsetMethod 
>>-unsetMethod (methodname)------------------------------------- >< 


Cancels the effect of all previous setMethods for method methodname. It also removes any method 
methodname introduced with enhanced when the object was created. If the object has received no 
setMethod method, no action is taken. 


Notes: 


1. The unsetMethod method is a private method. See the setPrivate method in setPrivate for details. 


2. The unsetMethod method is a protected method. 


5.1.2. The Class Class 


The Class class is like a factory that produces the factories that produce objects. It is a subclass of the 
Object class. The instance methods of the Class class are also the class methods of all classes. 
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Figure 5-2. The Class class and methods 
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5.1.2.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) — instanceMethod send 
=\= ==\== <> >< instanceMethods sendWith 


class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 
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5.1.2.2. baseClass 


>>-БавеСТавв-----ев- тата Зе таласа oS SSeS 4 >< 


Returns the base class associated with the class. If the class is a mixin class, the base class is the first 
superclass that is not also a mixin class. If the class is not a mixin class, the base class is the class 
receiving the baseClass message. 


5.1.2.3. defaultName 


>>2-даеғаш Маше === анаа aes >< 
Returns a short human-readable string representation of the class. The string returned is of the form 


The id class 


where id is the identifier assigned to the class when it was created. 


Examples: 


say .array defaultName /* Displays "The Array class" ж/ 
say .account^defaultName | /ж Displays "The ACCOUNT class" */ 
say .savings defaultName /* Displays "The Savings class" */ 


::class account /* Name is all upper case ж/ 
::class "Savings" /* String name is mixed case */ 


5.1.2.4. define 


»»-define(methodname-4--------- %-)----------------------------- >< 
+-,method-+ 


Incorporates the method object method in the receiver class’s collection of instance methods. The 
method name methodname is translated to to uppercase. Using the define method replaces any existing 
definition for methodname in the receiver class. 


If you omit method, the method name methodname is made unavailable for the receiver class. Sending a 
message of that name to an instance of the class causes the unknown method (if any) to be run. 


The method argument can be a string containing a method source line instead of a method object. 
Alternatively, you can pass an array of strings containing individual method lines. Either way, define 
creates an equivalent method object. 


Notes: 


1. The classes Rexx provides do not permit changes or additions to their method definitions. 
2. The define method is a protected method. 


Example: 


bank_account=.object~ subclass ("Account") 
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bank_account~define("TYPE",'return "a bank account"') 


5.1.2.5. delete 


»»-delete(methodname)------------------------------------------ >< 


Removes the receiver class’s definition for the method name methodname. If the receiver class defined 
methodname as unavailable with the define method, this definition is nullified. If the receiver class had 
no definition for methodname, no action is taken. 


Notes: 


1. The classes Rexx provides do not permit changes or additions to their method definitions. 


2. delete deletes only methods the target class defines. You cannot delete inherited methods the target’s 
superclasses define. 


3. The delete method is a protected method. 


Example: 

myclass=.object~subclass("Myclass") /* After creating a class ж/ 
myclass^define("TYPE",'return "my class"') /* and defining a method  */ 
myclass^delete("TYPE") /* this deletes the method */ 


5.1.2.6. enhanced 


»»-enhanced(methods-4--------------- %-)------------------------ >< 


| v | | 
+--- ,argument-—+-+ 


Returns an enhanced new instance of the receiver class, with object methods that are the instance 
methods of the class, enhanced by the methods in the collection methods. The collection indexes are the 
names of the enhancing methods, and the items are the method objects (or strings or arrays of strings 
containing method code). (See the description of define.) You can use any collection that supports a 
supplier method. 


enhanced sends an init message to the created object, passing the arguments specified on the enhanced 
method. 


Example: 


/* Set up rclass with class method or methods you want in your */ 
/* remote class */ 
rclassmeths = .directory^ new 


rclassmeths ["DISPATCH"]=d_source /* d source must have code for a ж/ 
/* DISPATCH method. ж/ 

/ж The following sends init("Remote Class") to a new instance */ 

rclass-.class^enhanced(rclassmeths, "Remote Class") 
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5.1.2.7. id 


Returns the class identity (instance) string. (This is the string that is an argument on the subClass and 
mixinClass methods.) The string representations of the class and its instances contain the class identity. 


Example: 


myobject-.object^subClass("my object") /* Creates a subclass ж/ 
say myobject~id /* Produces: "my object" */ 


5.1.2.8. inherit 


>>-inherit (classobj-+----------- %-)---------------------------- >< 
+-,classpos-+ 


Causes the receiver class to inherit the instance and class methods of the class object classobj. The 
classpos is a class object that specifies the position of the new superclass in the list of superclasses. (You 
can use the superClasses method to return the immediate superclasses.) 


The new superclass is inserted in the search order after the specified class. If the classpos class is not 
found in the set of superclasses, an error is raised. If you do not specify classpos, the new superclass is 
added to the end of the superclasses list. 


Inherited methods can take precedence only over methods defined at or above the base class of the 
classobj in the class hierarchy. Any subsequent change to the instance methods of classobj takes 
immediate effect for all the classes that inherit from it. 


The new superclass classobj must be created with the mixinClass option of the ::CLASS directive or the 
mixinClass method and the base class of the classobj must be a direct superclass of the receiver object. 
The receiver must not already descend from classobj in the class hierarchy and vice versa. 


The method search order of the receiver class after inherit is the same as before inherit, with the 
addition of classobj and its superclasses (if not already present). 


Notes: 


1. You cannot change the classes that Rexx provides by sending inherit messages. 
2. The inherit method is a protected method. 


Example: 


room~ inherit (.location) 


5.1.2.9. isSubClassOf 


»»-isSubclassÜ0f(class)------------------------------------- >< 
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Returns .true ("1") if the object is a subclass of the specified class. Returns .false ("0") if the object is not 
a subclass of the specified class. A class is a subclass of a class if the target class is the same as class or if 
class is in the object’s direct or mixin class inheritance chain. For example: 


. String~ isSubclassOf (.object) -> 1 
.String~isSubclassOf(.mutablebuffer) -> 0 


5.1.2.10. metaClass 


>р-шебабавв-------------------------------<-----<+ >< 


Returns Ше receiver class's default metaclass. This is Ше class used to create subclasses of this class 
when you send subClass or mixinClass messages (with no metaclass arguments). The instance methods 
of the default metaclass are the class methods of the receiver class. For more information about class 
methods, see Object Classes. See also the description of the subClass method in subClass. 


5.1.2.11. method 


>>-method (methodname)------------------------------------------ >< 


Returns the method object for the receiver class’s definition for the method name methodname. If the 
receiver class defined methodname as unavailable, this method returns the Nil object. If the receiver class 
did not define methodname, an error is raised. 


Example: 


/* Create and retrieve the method definition of a class */ 

myclass=.object~subClass("My class") /ж Create a class ж/ 
mymethod-.method^new(" ","Say arg(1)") /* Create а method object */ 
myclass^define("ECHO",mymethod) /* Define it in the class */ 
method source = myclass^method("ECHO")^source /* Extract it ж/ 
say method source /* Says "an Array" ж/ 
say method_source[1] /* Shows the method source code */ 


5.1.2.12. methods 


2»-methods-4---------------- BS DM ааа танкіні >< 
+-(class_object)-+ 


Returns a Supplier object for all the instance methods of the receiver class and its superclasses, if you 
specify no argument. If class_object is the Nil object, methods returns a supplier object for only the 
instance methods of the receiver class. If you specify a class_object, this method returns a supplier object 
containing only the instance methods that class_object defines. The supplier enumerates all the names 
and methods existing at the time of the supplier’s creation. 
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Note: Methods that have been hidden with a setMethod or define method are included with the 
other methods that methods returns. The hidden methods have the Nil object for the associated 
method. 


Example: 


objsupp=. object ~methods 
do while оБ)вирр available 


say objsupp' index -- displays all instance method 
objsupp^next -- names of the Object class 
end 


5.1.2.13. mixinClass 


»»-mixinClass(classid-4------------------------- %-)------------ >< 
%-,шефас1а55-%---------- +-+ 
+-,methods-+ 


Returns a new mixin subclass of the receiver class. You can use this method to create a new mixin class 
that is a subclass of the superclass to which you send the message. The classid is a string that identifies 
the new mixin subclass. You can use the id method to retrieve this string. 


The metaclass is a class object. If you specify metaclass, the new subclass is an instance of metaclass. (A 
metaclass is a class that you can use to create a class, that is, a class whose instances are classes. The 
Class class and its subclasses are metaclasses. ) 


If you do not specify a metaclass, the new mixin subclass is an instance of the default metaclass of the 
receiver class. For subclasses of the Object class, the default metaclass is the Class class. 


The methods is a collection whose indexes are the names of methods and whose items are method 
objects (or strings or arrays of strings containing method code). If you specify methods, the new class is 
enhanced with class methods from this collection. (The metaclass of the new class is not affected.) 


The metaClass method returns the metaclass of a class. 


The method search order of the new subclass is the same as that of the receiver class, with the addition of 
the new subclass at the start of the order. 


Example: 


buyable-.object^mixinClass("Buyable") /* New subclass is buyable */ 
/* Superclass is Object class */ 


5.1.2.14. new 
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Returns a new instance of the receiver class, whose object methods are the instance methods of the class. 
This method initializes a new instance by running its init methods. (See Initialization.) new also sends an 
init message. If you specify args, new passes these arguments on the init message. 


Example: 


/* new method example */ 


a = .account^new /* -» Object variable balance=0 */ 
y = .account^new(340.78) /* -» Übject variable balance-340.78 */ 
/* plus free toaster oven ж/ 


::class account subclass object 

::method init /* Report time each account created ж/ 
/* plus free toaster when more than $100 »/ 

Expose balance 

Arg opening. balance 

Say "Creating" self^objectName "at time" time() 

If datatype(opening balance, "N") then balance - opening balance 

else balance - 0 

If balance > 100 then Say " You win a free toaster oven" 


5.1.2.15. queryMixinClass 


>2-впегу оп тавв-------------------------------- >< 


Returns 1 (true) if Ше class is a mixin class, or 0 (false). 


5.1.2.16. subclass 


»»-subclass(classid-4------------------------- %-)-------------- >< 
%-,шефас1а5в-%---------- +-+ 
+-,methods-+ 


Returns a new subclass of the receiver class. You can use this method to create a new class that is a 
subclass of the superclass to which you send the message. The classid is a string that identifies the 
subclass. (You can use the id method to retrieve this string.) 


The metaclass is a class object. If you specify metaclass, the new subclass is an instance of metaclass. (A 
metaclass is a class that you can use to create a class, that is, a class whose instances are classes. The 
Class class and its subclasses are metaclasses.) 


If you do not specify a metaclass, the new subclass is an instance of the default metaclass of the receiver 
class. For subclasses of the Object class, the default metaclass is the Class class. 


The methods is a collection whose indexes are the names of methods and whose items are method 
objects (or strings or arrays of strings containing method code). If you specify methods, the new class is 
enhanced with class methods from this collection. (The metaclass of the new class is not affected.) 


The metaclass method returns the metaclass of a class. 


The method search order of the new subclass is the same as that of the receiver class, with the addition of 
the new subclass at the start of the order. 
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Example: 
room-.object^subclass("Room") /ж Superclass is .object */ 


/* Subclass is room ж/ 
/* Subclass identity is Room */ 


5.1.2.17. subclasses 


>2-виБстазвев------т--- ня а --------- >< 


Returns Ше immediate subclasses of the receiver class in Ше form of a single-index array of the required 
size, in an unspecified order. (The program should not rely on any order.) 


5.1.2.18. superClass 


2° “super 1азвя---н----- 3595549 >< 


Returns the immediate superclass of the receiver class. The immediate superclass is the original class 
used on a subClass or a mixinClass method. For the Object Class, superClass returns .Nil. 


Example: 

say .object^ superclass -- displays "The Nil object" 
say .class^superclass -- displays "The Object class" 
say .set^superclass -- displays "The Table class" 


5.1.2.19. superClasses 


>2-впрегетазвев----------------+-----<+- - а ааа >< 


Returns Ше immediate superclasses of Ше receiver class in Ше form of a single-index array of the 
required size. The immediate superclasses are the original class used on a subClass or a mixinClass 
method, plus any additional superclasses defined with the inherit method. The array is in the order in 
which the class has inherited the classes. The original class used on a subClass or mixinClass method is 
the first item of the array. 


Example: 


N 
Il 


.Class^superClasses 
/* To obtain the information this returns, you could use: */ 
do i over z 
say i 
end 


5.1.2.20. uninherit 


»»-uninherit(classobj)----------------------------------------- >< 
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Nullifies the effect of any previous inherit message sent to the receiver for the class classobj. 


Note: You cannot change the classes that Rexx provides by sending uninherit messages. 


Example: 


location=.object~mixinClass ("Location") 
room-.object^subclass("Room")^^inherit(location) /* Creates subclass */ 
/* and specifies inheritance */ 

room^uninherit (location) 


5.1.3. The String Class 


String objects represent character-string data values. A character string value can have any length and 
contain any characters. 
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Figure 5-3. The String class and methods 
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compare 
compareTo 
copies 
countstr 

d2c 

d2x 
dataType 
decodeBase64 
delStr 
delWord 
encodeBase64 
equals 
format 

insert 
lastPos 

left 

length 

lower 
makeArray 
makestring 
match 
matchChar 
max 

min 


overlay 
pos 
replaceAt 
reverse 
right 

sign 
space 
strip 
subChar 
subStr 
subWord 
translate 
trunc 
upper 
verify 
word 
wordindex 
wordLength 
wordPos 
words 
x2b 

х2с 

x2d 


Note: The String class also has available class methods that its metaclass, the Class class, defines. 
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5.1.3.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) instanceMethod send 


=\===\== <> >< instanceMethods sendWith 
class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


Methods inherited from the Comparable class. 


* compareTo 


5.1.3.2. new (Class Method) 


»»-new(stringvalue)-------------------------------------------- >< 


Returns a new string object initialized with the characters in stringvalue. 


5.1.3.3. Arithmetic Methods 


>>-arithmetic_operator (argument)------------------------------- >< 


Note: The syntax diagram above is for the non-prefix operators. The prefix + and argument. 


Returns the result of performing the specified arithmetic operation on the receiver object. The receiver 
object and the argument must be valid numbers (see Numbers). The arithmetic_operator can be: 


+ Addition 

- Subtraction 

Е Multiplication 

/ Division 

% Integer division (divide and return the integer part of the result) 

И Remainder (divide and return Ше remainder—not modulo, because Ше result can 
be negative) 

gi Exponentiation (raise a number to a whole-number power) 

Prefix - Same as the subtraction: 0 - number 

Prefix + Same as the addition: 0 + number 


See Numbers and Arithmetic for details about precision, the format of valid numbers, and the operation 
rules for arithmetic. Note that if an arithmetic result is shown in exponential notation, it might have been 
rounded. 
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Examples: 

5+5 -> 
8-5 -> 
5*2 -> 
6/2 -> 
9//4 -> 
9/4 -» 
2**3 -> 
+5 -> 
-5 -> 


10 


10 


anon е о» 


/ж 
/ж 


Prefix + ж/ 
Prefix - ж/ 


5.1.3.4. Comparison Methods 


>>-comparison_operator (argument) 


Returns 1 (true) or 0 (false), the result of performing the specified comparison operation. The receiver 
object and the argument are the terms compared. Both must be string objects. If argument is not a string 
object, it is converted to its string representation for the comparison. The one exception is when argument 
is the Nil object for the ==, \==, =, \=, ><, and <> operators. A string object will never compare equal 
to the Nil object, even when the string matches the string value of the Nil object ("The Nil object"). 


The comparison operators you can use in a message are: 


Examples: 
5-5 


42\=41 
42><41 
42<>41 


13>12 
12<13 
13>=12 
12\<13 
12<=13 
12\>13 


True if the terms are equal (for example, numerically or when padded) 


True if the terms are not equal (inverse of =) 


Greater than 


Less than 


Greater than or equal to 


Not less than 


Less than or equal to 


Not greater than 
1 /* equal 
1 /* All of these are 
1 /* "not equal" 
1 
/* Variations of 


/ж 
/ж 


во Ок въ 


less than and 
greater than 
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All strict comparison operations have one of the characters doubled that define the operator. The == and 
\== operators check whether two strings match exactly. The two strings must be identical (character by 
character) and of the same length to be considered strictly equal. 


The strict comparison operators such as >> or << carry out a simple character-by-character comparison. 
There is no padding of either of the strings being compared. The comparison of the two strings is from 
left to right. If one string is shorter than and a leading substring of another, then it is smaller than (less 
than) the other. The strict comparison operators do not attempt to perform a numeric comparison on the 
two operands. 


For all the other comparison operators, if both terms are numeric, the String class does a numeric 
comparison (ignoring, for example, leading zeros—see Numeric Comparisons). Otherwise, it treats both 
terms as character strings, ignoring leading and trailing whitespace characters and padding the shorter 
string on the right with blanks. 


Character comparison and strict comparison operations are both case-sensitive, and for both the exact 
collating order can depend on the character set. In an ASCII environment, the digits are lower than the 
alphabetic characters, and lowercase alphabetic characters are higher than uppercase alphabetic 
characters. 


The strict comparison operators you can use in a message are: 


== True if terms are strictly equal (identical) 


== True if the terms are NOT strictly equal (inverse of == 


>> Strictly greater than 

<< Strictly less than 

>>= Strictly greater than or equal to 

\<< Strictly NOT less than 

<<= Strictly less than or equal to 

\>> Strictly NOT greater than 

Examples: 

"space"=="space" -> 1 /* Strictly equal */ 
"space"\==" space" -> 1 /* Strictly not equal */ 
"space">>" space" -> 1 /* Variations of */ 
" space"<<"space" -> 1 /* strictly greater ж/ 
"space">>=" space" -> 1 /* than and less than */ 
"space"\<<" space" -> 1 

" space"<<="space" -> 1 

" space"\>>"space" -> 1 


5.1.3.5. Logical Methods 


>>-logical_operator (argument)---------------------------------- >< 
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Note: For NOT (prefix \), omit the parentheses and argument. 


Returns 1 (true) or o (false), the result of performing the specified logical operation. The receiver 
object and the argument are character strings that evaluate to 1 or o. 


The logical operator can be: 


& AND (Returns 1 if both terms are true.) 

| Inclusive OR (Returns 1 if either term or both terms are true.) 

&& Exclusive OR (Returns 1 if either term, but not both terms, is true.) 
Prefix V Logical NOT (Negates; 1 becomes 0, and 0 becomes 1.) 
Examples: 

1&0 -> 0 

110 -> 1 

1880 -> 1 

M -> 0 


5.1.3.6. Concatenation Methods 
»»-concatenation operator(argument)---------------------------- >< 


Concatenates the receiver object with argument. (See String Concatenation.) The 
concatenation_operator can be: 


пи пи 


concatenates without an intervening blank. The abuttal operator "" is the null 
string. The language processor uses the abuttal to concatenate two terms that 
another operator does not separate. 

Il concatenates without an intervening blank. 


"on 


concatenates with one blank between the receiver object and the argument. (The 
operator " " is a blank.) 


Examples: 
f — "abc" 
f"def" -> "abcdef" 
f || "def" -> "abcdef" 
f "def" -> "abc def" 


5.1.3.7. abbrev 


»»-abbrev(info-4--------- %-)----------------------------------- >< 
+-,length-+ 
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Returns 1 if info is equal to the leading characters of the receiving string and the length of info is not less 
than length. Returns 0 if either of these conditions is not met. 


If you specify length, it must be a positive whole number or zero. The default for length is the number of 
characters in info. 


Examples: 

"Print" ~abbrev("Pri") -> 1 
"PRINT" ~abbrev ("Pri") -> 0 
"PRINT" ~abbrev("PRI", 4) => 0 
"PRINT"^abbrev("PRY") -> 0 
"PRINT" ~abbrev("") -> 1 
"PRINT" ~abbrev("", 1) -> (0) 


Note: A null string always matches if a length of o, or the default, is used. This allows a default 
keyword to be selected automatically if desired. 


Example: 


say "Enter option:"; pull option . 

select /* keyword1 is to be the default */ 
when "keywordi"^abbrev(option) then ... 
when "keyword2"~abbrev(option) then ... 


otherwise nop; 
end; 


5.1.3.8. abs 


Returns the absolute value of the receiving string. The result has no sign and is formatted according to 
the current NUMERIC settings. 


Examples: 
12.3^abs -> 12.3 
"-0.307"^abs -> 0.307 


5.1.3.9. b2x 


Returns a string, in character format, that represents the receiving binary string converted to hexadecimal. 


The receiving string is a string of binary (0 or 1) digits. It can be of any length. It can optionally include 
whitespace characters (at 4-digit boundaries only, not leading or trailing). These are to improve 
readability and are ignored. 
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The returned string uses uppercase alphabetic characters for the values A-F and does not include 
whitespace. 


If the receiving binary string is a null string, b2x returns a null string. If the number of binary digits in 
the receiving string is not a multiple of four, up to three 0 digits are added on the left before the 
conversion to make a total that is a multiple of four. 


Examples: 

"11000011"~b2x -> "C3" 
"10111"7Ь2х -> "17" 
"101"7Ь2х -> "5" 


"1 1111 0000"^b2x -> "1FO" 


You can combine b2x with the methods x2d and x2c to convert a binary number into other forms. 


Example: 


"10111"^b2x^x2d -> "23" /* decimal 23 */ 


5.1.3.10. bitAnd 


зърна те ашы Е ee а 
+-(string-+------+-)-+ 
+-,pad-+ 


Returns a string composed of the receiver string and the argument string logically ANDed together, bit 
by bit. (The encodings of the strings are used in the logical operation.) The length of the result is the 
length of the longer of the two strings. If you omit the pad character, the AND operation stops when the 
shorter of the two strings is exhausted, and the unprocessed portion of the longer string is appended to 
the partial result. If you provide pad, it extends the shorter of the two strings on the right before the 
logical operation. The default for string is the zero-length (null) string. 


Examples: 

"12"x^bitAnd -> "12"х 

"T3"x^bitAnd("27"x) -> "23"x 
"13"x^bitAnd("5555"x) -> "1155"x 
"13"x~bitAnd("5555"x,"74"x) -> "1154"x 

"pQrS"^bitAnd(, "РЕ"х) -> "PQRS" /* ASCII  */ 


5.1.3.11. bitOr 


ала EE с et Eek АРТА боқ ал. Сев ee eee " 
+-(string-+------+-)-+ 
+-,pad-+ 


Returns a string composed of the receiver string and the argument string logically inclusive-ORed, bit by 
bit. The encodings of the strings are used in the logical operation. The length of the result is the length of 
the longer of the two strings. If you omit the pad character, the OR operation stops when the shorter of 
the two strings is exhausted, and the unprocessed portion of the longer string is appended to the partial 
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result. If you provide pad, it extends the shorter of the two strings on the right before the logical 
operation. The default for string is the zero-length (null) string. 


Examples: 

"12"x^bitOr -> "12"x 
"15"x^bitOr("24"x) -> "35"x 
"15"x^bitOr("2456"x) -> "3556"x 
"15"x^bitOr("2456"x,"FO"x) -> "35F6"x 
"1111"x^bitOr(,"4D"x) -> "Бр5р"х 
"pQrS"~bitOr(,"20"x) -> "pqrs" /ж ASCII */ 


5.1.3.12. bitXor 


SS “pitvorse ы са Шаа Tum » 
+-(string-+------+-)-+ 
+-,pad-+ 


Returns a string composed of the receiver string and the argument string logically eXclusive-ORed, bit 
by bit. The encodings of the strings are used in the logical operation. The length of the result is the length 
of the longer of the two strings. If you omit the pad character, the XOR operation stops when the shorter 
of the two strings is exhausted, and the unprocessed portion of the longer string is appended to the partial 
result. If you provide pad, it extends the shorter of the two strings on the right before carrying out the 
logical operation. The default for string is the zero-length (null) string. 


Examples: 
"12"x^bitXor -> "12"x 
"12"x^bitXor("22"x) -> "30"x 
"1211"x^bitXor("22"x) -> "3011"x 
"1111"x^bitXor("444444"x) -> "555544"x 
"1111"x^bitXor("444444"x,"A0"x) -> "555504"х 
"1111"x^bitXor(,"AD"x) -> "5C5C"x 
"C711i"x^bitXor("222222'"x," ") -> "Е53302"х /ж ASCII */ 
5.1.3.13. c2d 
>>-с24-+----- %------------------------------------------------- >< 
+-(n)-+ 


Returns the decimal value of the binary representation of the receiving string. If the result cannot be 
expressed as a whole number, an error results. That is, the result must not have more digits than the 
current setting of NUMERIC DIGITS. If you specify n, it is the length of the returned result. If you do 
not specify n, the receiving string is processed as an unsigned binary number. If the receiving string is 
null, C2D returns 0. 


Examples: 
"09"X^c2d -> 9 
"81"X^c2d -> 129 
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"FF81"X^c2d -> 65409 
""“сда -> 0 
"a"^c2od -» 97 /ж ASCII ж/ 


If you specify п, the receiving string is taken as a signed number expressed in п characters. The number 
is positive if the leftmost bit is off, and negative if the leftmost bit is on. In both cases, it is converted to a 
whole number, which can therefore be negative. The receiving string is padded on the left with "00"x 
characters (not "sign-extended"), or truncated on the left to п characters. This padding or truncation is as 
though receiving string^right (n,'00'x) had been processed. If n is 0, c2d always returns 0. 


Examples: 

"81"X^c2d(1) -> -127 
"81"X~c2d(2) -> 129 
"FF81"X^c2d(2) -> -127 
"FF81"X^c2d(1) -> -127 
"FF7F"X^c2d(1) -> 127 
"FO81"X~c2d(2) -> -3967 
"FO81"X~c2d(1) -> -127 
"0031"X^c2d(0) -> 0 


5.1.3.14. c2x 


Returns а string, in character format, that represents the receiving string converted to hexadecimal. The 
returned string contains twice as many bytes as the receiving string. On an ASCII system, sending a c2x 
message to the receiving string 1 returns 31 because "31"X is the ASCII representation of 1. 


The returned string has uppercase alphabetic characters for the values A-F and does not include 
whitespace. The receiving string can be of any length. If the receiving string is null, c2x returns a null 


string. 

Examples: 

"0123"X^c2x -> "0123" /ж "30313233"X in ASCII ж/ 
"ZD8"~c2x -> "5Д4438" /ж "354134343338"X in ASCII */ 


5.1.3.15. caselessAbbrev 


>>-caselessAbbrev(info-+--------- Wa) MESS = 25S ааа ве S SS SS S52 === >< 
+-,length-+ 


Returns 1 if info is equal to the leading characters of the receiving string and the length of info is not less 
than length. Returns 0 if either of these conditions is not met. The characters are tested using a caseless 
comparison. 


If you specify length, it must be a positive whole number or zero. The default for length is the number of 
characters in info. 


Examples: 
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"Print"~caselessAbbrev("Pri") -> 1 
"PRINT"^caselessAbbrev ("Pri") -> 1 
"PRINT" ~caselessAbbrev("PRI", 4) -> 0 
"PRINT" ~caselessAbbrev ("PRY") -> 0 
"PRINT" ~caselessAbbrev("") -> 1 
"PRINT" ~caselessAbbrev("",1) -> 0 


Note: A null string always matches if a length of 0, or the default, is used. This allows a default 
keyword to be selected automatically if desired. 


Example: 


say "Enter option:"; parse pull option . 

select /ж keywordi is to be the default */ 
when "keywordi"^caselessAbbrev(option) then ... 
when "keyword2"^caselessAbbrev(option) then ... 


otherwise nop; 
end; 


5.1.3.16. caselessChangeStr 


>>-caselessChangeStr (needle,newneedle--4-------- %--)--------------------------------- >< 
+-,count-+ 


Returns a copy of the receiver object in which newneedle replaces occurrences of needle. If count is not 
specified, all occurrences of needle are replaced. If count is specified, it must be a positive, whole 
number that gives the maximum number of occurrences to be replaced. The needle searches are 
performed using caseless comparisons. 


Here are some examples: 


"AbaAbb"^caselessChangeStr("A","") -> "bbb" 
AbaBabAB^ changeStr("ab","xy") -> "хухухуху" 
AbaBabAB^ changeStr("ab", "xy", 1) -> "xyaBabAB" 


5.1.3.17. caselessCompare 


»»-caselessCompare(string-*------ %-)----------------------------------- >< 
+-,pad-+ 


Returns 0 if the argument string is identical to the receiving string using a caseless comparison. 
Otherwise, returns the position of the first character that does not match. The shorter string is padded on 
the right with pad if necessary. The default pad character is a blank. 


Examples: 


"abc" ~caselessCompare ("АВС") -> 0 
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"abc" ~caselessCompare ("Ak") -> 2 

"ab "~caselessCompare ("AB") => 0 

"AB "^caselessCompare("ab"," ") -> 0 

"ab "^caselessCompare("ab","x") -> 3 

"abXX "^caselessCompare("ab","x") -> Б 

5.1.3.18. caselessCompareTo 
»»-caselessCompareTo(string-*----------------------- ала) SSS SSeS a ан кана >< 

%-,--%-- +--+--------- +-+ 


%-п-% +-,length-+ 


Performs а caseless sort comparison of Ше target string to Ше string argument. If the two strings are 
equal, 0 is returned. If the target string is larger, 1 is returned. -1 if the string argument is the larger 
string. The comparison is performed starting at character n for length characters in both strings. n must 
be a positive whole number. If 7 is omitted, the comparison starts at the first character. length must be a 
non-negative whole number. If ommitted, the comparison will take place to the end of the target string. 


Examples: 

"abc"^caselessCompareTo("abc") -> 
"b"~caselessCompareTo("a" -> 1 
"a"^caselessCompareTo("b") => o 
"abc"^caselessCompareTo("aBc") -> 0 
"aBc"^caselessCompareTo("abc") -> 0 


"000abc000"~caselessCompareTo(11labc11i1", 4, 3) -> 0 


5.1.3.19. caselessCountStr 


>>-caselessCountStr (needle)-------------------------------------------- >< 


Returns a count of the occurrences of needle in the receiving string that do not overlap. All matches are 
made using caseless comparisons. 


Here are some examples: 


"a0Aa0A"^caselessCountStr('a" => 
"JOkKkO"~caselessCountStr ("КК") -> 1 


5.1.3.20. caselessEquals 


»»-caselessEquals (other)----------------------------------------------- >< 


Returns .true ("1") if the target string is strictly equal to the other string, using а caseless comparison. 
Returns .false ("0") if the two strings are not strictly equal. Examples: 


"a"~caselessEquals ("А") -» 1 
"aa"^caselessEquals("A") -» 
"4"~caselessEquals ("3") -» 0 
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5.1.3.21. caselessLastPos 


>>-caselessLastPos (needle-4--------------------------- %-)--->< 
%-,--%------- %--%--------- +-+ 
*t-start-* +-,length-+ 


Returns the position of the last occurrence of a string, needle, in the receiving string. (See also POS.) It 
returns 0 if needle is the null string or not found. By default, the search starts at the last character of the 
receiving string and scans backward to the beginning of the string. You can override this by specifying 
start, the point at which the backward scan starts and length, the range of characters to scan. The start 
must be a positive whole number and defaults to receiving_string~ length if larger than that value or 
omitted. The /ength must be a non-negative whole number and defaults to start. The search is performed 
using caseless comparisons. 


Examples: 

"abc def ghi"^caselessLastPos(" ") -> 8 

"abcdefghi"^caselessLastPos(" ") -> 0 

"efgxyz"~ caselessLastPos ("ХҮ") -> 4 

"арс def ghi"~caselessLastPos(" ",7) -> 4 

"арс def ghi"^caselessLastPos(" ",7,3) -> 0 

5.1.3.22. caselessMatch 

»»-caselessMatch(start,other-4---------------------------- a a --- + 5 >< 
+- ,--+---+--+---------+-+ 


+-n-+ +-,length-+ 


Returns .true ("1") if the characters of the other match the characters of the target string beginning at 
position start. Return .false ("0") if the characters are not a match. The matching is performed using 
caseless comparisons. start must be a positive whole number less than or equal to the length of the target 
string. 


If n is specified, the match will be performed starting with character n of other. The default value for n is 
"1". n must be a positive whole number less than or equal to the length of other. 


If length is specified, it defines a substring of other that is used for the match. length must be a positive 
whole number and the combination of n and length must be a valid substring within the bounds of other. 


The caselessMatch method is useful for efficient string parsing as it does not require new string objects 
be extracted from the target string. 


Examples: 
"Saturday"^caselessMatch(6, "day") => 
"Saturday"^caselessMatch(6, "DAY") -» 


"Saturday"^caselessMatch(6, "SUNDAY", 4, 3) -> 
"Saturday"^caselessMatch(6, "daytime", 1, 3) -> 


PPP Pe 
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5.1.3.23. caselessMatchChar 


>>-caselessMatchChar (n, chars) ------------------------- >< 


Returns .true ("1") if the character at position n matches any character of the string chars. Returns .false 
("0") if the character does not match any of the characters in the reference set. The match is made using 
caseless comparisons. The argument n must be a positive whole number less than or equal to the length 
of the target string. 


Examples: 
"at+b"~caselessMatchChar(2, "+-*/") -> 1 
"at+b"~caselessMatchChar(1, "+-¥*/") -> 0 
"Friday"^caselessMatchChar(3, "aeiou") -> 1 
"FRIDAY" ~caselessMatchChar(3, "aeiou") -> 1 
5.1.3.24. caselessPos 
»»-caselessPos(needle-4--------------------------- %-)--->< 
%-,--%------- %------------ +-+ 


И 


*t-start-* +-,length-+ 


Returns the position in the receiving string of another string, needle. (See also caselessLastPos.) It returns 
0 if needle is the null string or is not found or if start is greater than the length of the receiving string. The 
search is performed using caseless comparisons. By default, the search starts at the first character of the 
receiving string (that is, the value of start is 1), and continues to the end of the string. You can override 
this by specifying start, the point at which the search starts, and length, the bounding limit for the search. 
If specified, start must be a positive whole number and length must be a non-negative whole number. 


Examples: 

"Saturday"~caselessPos ("DAY") -» 6 

"abc def ghi"^caselessPos("x") -> 0 

"арс def ghi"~caselessPos(" ") -> 4 

"арс def ghi"~caselessPos(" ",5) -> 8 

"abc def ghi"^caselessPos(" ",5,3) -> 0 

5.1.3.25. caselessWordPos 

»»-caselessWordPos(phrase-4-------- %-)--------------------------------- >< 


+-,start-+ 


Returns the word number of the first word of phrase found in the receiving string, or 0 if phrase contains 
no words or if phrase is not found. Word matches are made independent of case. Several whitespace 
characters between words in either phrase or the receiving string are treated as a single blank for the 
comparison, but, otherwise, the words must match exactly. 


By default the search starts at the first word in the receiving string. You can override this by specifying 
start (which must be positive), the word at which the search is to be started. 


Examples: 
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"now is the time"~caselessWordPos ("the") =>: 3 

"now is the time"~caselessWordPos ("Тһе") -> 3 

"now is the time"~caselessWordPos("IS THE") -> 2 

"now is the time"^caselessWordPos("is the") -> 2 

"now is the time"^caselessWordPos("is time ") -> 0 

"To be or not to be"^caselessWordPos("BE") -> 2 

"To be or not to be"^caselessWordPos("BE",3) -> 6 
5.1.3.26. center/centre 

>>-+-center (-+-length-+-------- ж) a a nsssSnse se aes-= >< 


*-centre(-* %-,--рай-- 


Returns a string of length length with the receiving string centered in it. The pad characters are added as 
necessary to make up length. The length must be a positive whole number or zero. The default pad 
character is blank. If the receiving string is longer than length, it is truncated at both ends to fit. If an odd 
number of characters are truncated or added, the right-hand end loses or gains one more character than 
the left-hand end. 


Note: To avoid errors because of the difference between British and American spellings, this method 
can be called either center or centre. 


Examples: 

ас” center (7) -> " ABC " 
abc^CENTER(8 , "-") -> TARAB == 
"The blue sky"~centre(8) -> "e blue s" 
"The blue sky"~centre(7) -» "e blue " 


5.1.3.27. changeStr 


>>-changeStr (needle ,newneedle--4-------- %--)--------------------------------- >< 


Returns а copy of the receiver object in which newneedle replaces occurrences of needle. 


If count is not specified, all occurrences of needle are replaced. If count is specified, it must be a positive, 
whole number that gives the maximum number of occurrences to be replaced. 


Here are some examples: 


101100~changeStr("1","") -> "000" 
101100~changeStr("1","X") -> "XOXXOO" 
101100^changeStr("1","X",1) -> "X01100" 
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5.1.3.28. compare 


»»-compare(string-4------ Fjart ecenin Eae >< 
+-,pad-+ 


Returns 0 if the argument string is identical to the receiving string. Otherwise, returns the position of the 
first character that does not match. The shorter string is padded on the right with pad if necessary. The 
default pad character is a blank. 


Examples: 

"abc" ~compare ("арс") -» 0 

"abc"^compare("ak") -> 2 

"ab "^compare("ab") -> 0 

"ab "^compare("ab"," ") -> 0 

"ab "^compare("ab","x") -> 3 

"ab-- ""compare("ab" Е "-") -> 5 

5.1.3.29. compareTo 

»»-compareTo(string-*----------------------- 4x)--------22--2--22-2-2--- >< 
%-,--%-- %--4--------- +-+ 


%-п-% +-,length-+ 


Performs a sort comparison of Ше target string to Ше string argument. If the two strings are equal, 0 is 
returned. If the target string is larger, 1 is returned. -1 if the string argument is the larger string. The 
comparison is performed starting at character n for length characters in both strings. n must be a positive 
whole number. If и is omitted, the comparison starts at the first character. length must be a non-negative 
whole number. If ommitted, the comparison will take place to the end of the target string. 


Examples: 

"abc"^compareTo("abc") -» 
"b"~compareTo("a" -» 1 
"a"^compareTo("b") -> -1 
"abc"^compareTo("aBc") -> 1 
"aBc"~compareTo("abc") =>, 251 


"000abc000"~compareTo(111labc111", 4, 3) -> 0 


5.1.3.30. copies 


»»-copies(n)--------------------------------------------------- >< 


Returns п concatenated copies of the receiving string. The must be a positive whole number or zero. 


Examples: 
"abc" ~copies (3) -» "abcabcabc" 
"abc"^copies(0) -» ny 
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5.1.3.31. countStr 
»»-count$Str(needle)-------------------------------------------- >< 


Returns a count of the occurrences of needle in the receiving string that do not overlap. 


Here are some examples: 


"101101"~countStr ("1") -> 4 

" JOKKKO"~CountStr ("KK") -> 1 

5.1.3.32. d2c 

>>-42с-+----- %------------------------------------------------- >< 
+-(n)-+ 


Returns a string, in character format, that is the ASCII representation of the receiving string, a decimal 
number. If you specify n, it is the length of the final result in characters; leading blanks are added to the 
returned string. The и must be a positive whole number or zero. 


The receiving string must not have more digits than the current setting of NUMERIC DIGITS. 


If you omit n, the receiving string must be a positive whole number or zero, and the result length is as 
needed. Therefore, the returned result has no leading "00"x characters. 


Examples: 

"65"^d2c -> "a" /* "41"x is an ASCII "A" ж/ 
"65"^d2c(1) -> "a" 

"65"^d2c(2) -> "a" 

"65"^d2c(5) -> " A" 

"109"^d2c -> "m" /* "6D"x is an ASCII "m" */ 
"-109"^d2c(1) -> "ё" /* "93"x is an ASCII "ô" */ 
"76"~d2c (2) -> "I" /* "4C"x is an ASCII " L" */ 
"-180"742с(2) -> "І" 


Implementation maximum: The returned string must not have more than 250 significant characters, 
although a longer result is possible if it has additional leading sign characters ("00"х and "FF"x). 


5.1.3.33. d2x 


>>-42х-+----- %------------------------------------------------- >< 
+-(n)-+ 


Returns a string, in character format, that represents the receiving string, a decimal number converted to 
hexadecimal. The returned string uses uppercase alphabetic characters for the values A-F and does not 
include whitespace. 


The receiving string must not have more digits than the current setting of NUMERIC DIGITS. 
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If you specify n, it is the length of the final result in characters. After conversion the returned string is 
sign-extended to the required length. If the number is too big to fit into n characters, it is truncated on the 
left. If you specify n, it must be a positive whole number or zero. 


If you omit n, the receiving string must be a positive whole number or zero, and the returned result has 
no leading zeros. 


Examples: 

"Q"^d2x -> "9" 
"129"~d2x -> "81" 
"129"742х(1) -> "1" 
"129"742х(2) -> "81" 
"129"742х(4) -> "0081" 
"257"~d2x(2) -> "01" 
"-127"742х(2) -> "81" 
"-127""d2x(4) -> "FF81" 
"12"^d2x(0) -> пи 


Implementation maximum: The returned string must not have more than 500 significant hexadecimal 
characters, although a longer result is possible if it has additional leading sign characters (0 and F). 


5.1.3.34. dataType 


>>-датаТуре-+-------- Есте ---------- a >< 
+-(туре) -+ 


Returns NUM if you specify no argument and Ше receiving string is a valid Rexx number Ша! can be added 
to 0 without error. It returns CHAR if the receiving string is not a valid number. 


If you specify type, it returns 1 if the receiving string matches the type. Otherwise, it returns 0. If the 
receiving string is null, the method returns 0 (except when the type is X or B, for which dataType returns 
1 for a null string). The following are valid types. You need to specify only the capitalized letter, or the 
number of the last type listed. The language processor ignores all characters surrounding it. 


Alphanumeric 


returns 1 if the receiving string contains only characters from the ranges a-z, A-Z, and 0-9. 


Binary 


returns 1 if the receiving string contains only the characters 0 or 1, or whitespace. Whitespace 
characters can appear only between groups of 4 binary characters. It also returns | if string is a null 
string, which is a valid binary string. 


Lowercase 


returns 1 if the receiving string contains only characters from the range a-z. 


Mixed case 


returns 1 if the receiving string contains only characters from the ranges a-z and A-Z. 
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Number 


returns 1 if receiving string^dataType returns NUM. 


lOgical 


returns 1 if the receiving string is exactly "0" or "1". Otherwise it returns 0. 


Symbol 
returns 1 if the receiving string is a valid symbol, that is, if SYMBOL(string) does not return BAD. 
(See Symbols.) Note that both uppercase and lowercase alphabetic characters are permitted. 
Uppercase 


returns 1 if the receiving string contains only characters from the range A-Z. 


Variable 
returns 1 if the receiving string could appear on the left-hand side of an assignment without causing 
a SYNTAX condition. 

Whole number 


returns 1 if the receiving string is a whole number under the current setting of NUMERIC DIGITS. 


heXadecimal 


returns 1 if the receiving string contains only characters from the ranges a-£, A-F, 0-9, and 
whitespace characters (as long as whitespace characters appear only between pairs of hexadecimal 
characters). Also returns 1 if the receiving string is a null string. 


9 Digits 

returns 1 if receiving string^dataType("W") returns 1 when NUMERIC DIGITS is set to 9. 
Examples: 
" 12 "“dataType -> "NUM" 
"""dataType -> "CHAR" 
"123*"~dataType -> "CHAR" 
"12.3"^dataType("N") > 1 
"12.3"^dataType("W") > 0 
"Fred"^dataType("M") -> 1 
"""dataType("M") -> 0 
"Fred"^dataType("L") -> 0 
"?20K"^dataType("s") -> 1 
"BCd3"^dataType("X") > 1 
"BC d3"^dataType("X'") > 1 
"1"~dataType("0") -> 1 
"11"~dataType("0") -> 0 


Note: The dataType method tests the meaning or type of characters іп а string, independent of the 
encoding of those characters (for example, ASCII or EBCDIC). 
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5.1.3.35. decodeBase64 


>> -десодеВавеб4------------------#---5-------+----+---#-+------ >< 
Returns а new string containing Ше decoded version of Ше base64 encoded receiving string. If the 
receiving string is not in base64 format then the returned result is undefined. 


Examples: 


"YWJjZGVm" ^decodeBase64 -> "abcdef" 


5.1.3.36. delStr 


»»-delStr(n--4--------- $--2)ez-------82--0--9---4-4------48---54-- >< 
+-,length-+ 


Returns a copy of the receiving string after deleting the substring that begins at the nth character and is of 
length characters. If you omit length, or if length is greater than the number of characters from n to the 
end of string, the method deletes the rest of string (including the nth character). The length must be a 
positive whole number or zero. The n must be a positive whole number. If n is greater than the length of 
the receiving string, the method returns the receiving string unchanged. 


Examples: 

"abcd"^delStr(3) -> "ар" 

"abcde" ~delStr (3,2) -> "abe" 

"abcde" ~delStr (6) -> "abcde" 

5.1.3.37. delWord 

»»-delWord(n--4--------- i а >< 


+-,length-+ 


Returns a copy of the receiving string after deleting the substring that starts at the nth word and is of 
length blank-delimited words. If you omit length, or if length is greater than the number of words from n 
to the end of the receiving string, the method deletes the remaining words in the receiving string 
(including the nth word). The length must be a positive whole number or zero. The n must be a positive 
whole number. If и is greater than the number of words in the receiving string, the method returns the 
receiving string unchanged. The string deleted includes any whitespace characters following the final 
word involved but none of the whitespace characters preceding the first word involved. 


Examples: 
"Now is the time"~delWord(2,2) -> "Now time" 
"Now is the time "~delWord(3) -» "Now is " 


"Now is the time"~delWord(5) -» "Now is the time" 
"Now is the time"^delWord(3,1) -> "Now is time" 
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5.1.3.38. encodeBase64 
>>-аепсодеВавеб4------------------+-----------<+<+-+--+-+-#++-#---+ >< 


Returns a new string that is Ше base64 encoded version of Ше receiving string. 


Examples: 


"abcdef"^encodeBase64 -> "YWJjZGVm" 


5.1.3.39. equals 


>>-equals (other)------------------------------------------------------- >< 


Returns .true ("1") if the target string is strictly equal to the other string. Returns false ("0") if the two 


strings are not strictly equal. This is the same comparison performed by the "==" comparison method. 
Examples: 
"3"~equals("3") -> 1 
"33"^equals("3") -> 
"4"~equals("3") -> 0 
5.1.3.40. format 
>>-Ғогпа%-%--------------------------------------------------------- %->< 
*-(-before-4------------------------------------------ T-)-* 
%-,--%------- %--%------------------------ +-+ 
+-after-+ +-,--+------+--+-------+-+ 


%-ехрр-% +-,expt-+ 


Returns a copy of the receiving string, a number, rounded and formatted. 


The number is first rounded according to standard Rexx rules, as though the operation 
receiving_string+0 had been carried out. If you specify no arguments the result of the method is the 
same as the result of this operation. If you specify any options, the number is formatted as described in 
the following. 


The before and after options describe how many characters are to be used for the integer and decimal 
parts of the result. If you omit either or both of them, the number of characters for that part is as needed. 


If before is not large enough to contain the integer part of the number (plus the sign for a negative 
number), an error results. If before is larger than needed for that part, the number is padded on the left 
with blanks. If after is not the same size as the decimal part of the number, the number is rounded (or 
extended with zeros) to fit. Specifying 0 causes the number to be rounded to an integer. 


Examples: 

"3"~format (4) -> "og 
"1.73"^format(4,0) -> ДИРИ 
"1.73"~format (4,3) -> " 1.730" 
"-.76"^format(4,1) -> " -0.8" 
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"3.03"~format (4) -> Ы 3.03" 
" - 12.73"^format(,4) => "-12.7300" 
" - 12.73"^format -> "-12.73" 
"0.000"~format -> "о" 


expp and expt control the exponent part of the result, which, by default, is formatted according to the 
current NUMERIC settings of DIGITS and FORM. expp sets the number of places for the exponent part; 
the default is to use as many as needed (which can be zero). expt specifies when the exponential 
expression is used. The default is the current setting of NUMERIC DIGITS. 


If expp is 0, the number is not an exponential expression. If expp is not large enough to contain the 
exponent, an error results. 


If the number of places needed for the integer or decimal part exceeds expt or twice expt, respectively, 
exponential notation is used. If expt is 0, exponential notation is always used unless the exponent would 
be 0. (If expp is 0, this overrides a 0 value of expt.) If the exponent would be 0 when a nonzero expp is 
specified, then expp+2 blanks are supplied for the exponent part of the result. If the exponent would be 0 
and expp is not specified, the number is not an exponential expression. 


Examples: 

"12345.73"~format(, ,2,2) -> "1.234573Е+04" 
"12345 .73"~format(,3, ,0) -> "1.235Е+4" 
"1.234573"^format(,3, ,0) -> "1.235" 
"12345.73" Ғогтаї(, ,3,6) -> "12345.73" 
"1234567e5"~format(,3,0) -> "123456700000.000" 


5.1.3.41. hashCode 


>>-паврбоде-----------------<- SSS See Eee >< 


Returns a string value that is used as a hash value for MapCollection such as Table, Relation, Set, Bag, 
and Directory. The String hash code method will return the same hash value for all pairs of string 
instances for which the == operator is true. See hashCode Method for details. 


5.1.3.42. insert 


»»-insert (new---------------------------------------- %-)------ >< 
%-,--%---%--%------------------------- +-+ 


, 
%-п-%  4-,--4--------4--4------4- 
+-length-+ +-,pad-+ 


Returns a copy of the receiver string with the string new, padded or truncated to length length, inserted 
after the nth character. The default value for n is 0, which means insertion at the beginning of the string. 
If specified, n and length must be positive whole numbers or zero. If n is greater than the length of the 
receiving string, the string new is padded at the beginning. The default value for length is the length of 
new. If length is less than the length of the string new, then insert truncates new to length length. The 
default pad character is a blank. 


Examples: 


152 ooRexx Reference Version 4.0.0 


Chapter 5. The Builtin Classes 


"abc" insert ("123") -> "123abc" 
"abcdef"^insert(" ",3) -> "abc def" 
"abc"~ insert ("123",5,6) -> "арс 123 " 
"abc"^insert("123",5,6,"4") -> "арс++123+++" 
"abc"^insert("123", ,5,"-") -> "123--abc" 


5.1.3.43. lastPos 


»»-lastPos (needle-4--------------------------- %-)--->< 
%-,--%------- %--%--------- +-+ 
*-start-* +-,length-+ 


Returns the position of the last occurrence of a string, needle, in the receiving string. (See also POS.) It 
returns 0 if needle is the null string or not found. By default, the search starts at the last character of the 
receiving string and scans backward to the beginning of the string. You can override this by specifying 
start, the point at which the backward scan starts and length, the range of characters to scan. The start 
must be a positive whole number and defaults to receiving string" length if larger than that value or 
omitted. The /ength must be a non-negative whole number and defaults to start. 


Examples: 

"abc def ghi"^lastPos(" ") -> 8 

"abcdefghi"^lastPos(" ") -> 0 

"efgxyz"^lastPos("xy") -> 4 

"арс def ghi"~lastPos(" ",7) -> 4 

"abc def ghi"^lastPos(" ",7,3) -> 0 

5.1.3.44. left 

>>-left (length-4------ %-)-------------------------------------- >< 


+-,pad-+ 


Returns a string of length length, containing the leftmost length characters of the receiving string. The 
string returned is padded with pad characters (or truncated) on the right as needed. The default pad 
character is a blank. The length must be a positive whole number or zero. The left method is exactly 
equivalent to: 


»»-SUBSTR(string,1,length-4*------ %-)--------------------------- >< 
+-,pad-+ 

Examples: 

"abc d"~left (8) -> "арса " 

"арс d"^left(8,".") -> "арс а..." 

"арс def"~left(7) -> "арс де" 
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5.1.3.45. length 


D2 LONG tse See sso eee eS a ee cease >< 


Returns the length of the receiving string. 


Examples: 

"abcdefgh"^length -> 8 

"арс defg"” length -> 8 

""~length -» 0 

5.1.3.46. lower 

>>-lower (+---+--+--------- %---)---------------------- >< 


%-п-% +-,length-+ 


Returns a new string with the characters of the target string beginning with character n for length 
characters converted to lowercase. If n is specified, it must be a positive whole number. If is not 
specified, the case conversion will start with the first character. If length is specified, it must be a 

non-negative whole number. If length the default is to convert the remainder of the string. 


Examples: 

"Albert Einstein"~ lower -> "albert einstein" 
"ABCDEF" ~ lower (4) -> "ABCdef" 
"ABCDEF"~ lower (3,2) -> "ABcdEF" 


5.1.3.47. makeArray 


»»-makeArray(-4----------- %-)---->< 
+-Separator-+ 


This method returns an array of strings containing the single lines that were separated using the 
separator string. The separator may be any string, including the null string. If the null string is used, an 
array containing each character of the string is returned. If the target string starts with the separator, the 
first array item will be a null string. If the string ends with a separator, no extra null string item will be 
added. The default separator is the newline character. 


Example: 
string = "hello".endofline"world".endofline"this is an array." 


array = string makeArray 
say "the second line is:" array[2] /* world */ 


string - "hello*world*this is an array." 
array = string~makeArray("*" 


say "the third line is:" array[3] /* this is an array. ж/ 


string = "hello*world*this is an array.*" 
array = string~makeArray("*" /* contains 3 items */ 
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5.1.3.48. makeString 


Po MAKES tring sss SSS Sass SS ans SS sesh eer Sasser nese Sasa sae ce >< 


Returns a string with the same string value as the receiver object. If the receiver is an instance of a 
subclass of the String class, this method returns an equivalent string object. If the receiver is a string 
object (not an instance of a subclass of the String class), this method returns the receiver object. See 
Required String Values. 


5.1.3.49. match 


>>-match (start ,other-+---------------------------- %-)------------------- >< 
%-,--%---4--%---------4-% 
%-п-% +-,length-+ 


Returns .true ("1") if the characters of the other match the characters of the target string beginning at 
position start. Return .false ("0") if the characters are not a match. start must be a positive whole number 
less than or equal to the length of the target string. 


If n is specified, the match will be performed starting with character n of other. The default value for n is 
"1". n must be a positive whole number less than or equal to the length of other. 


If length is specified, it defines a substring of other that is used for the match. length must be a positive 
whole number and the combination of n and length must be a valid substring within the bounds of other. 


The match method is useful for efficient string parsing as it does not require new string objects be 
extracted from the target string. 


Examples: 

"Saturday"^match(6, "day") -> 1 
"Saturday"^match(6, "DAY") -» 0 
"Saturday"^match(6, "Sunday", 4, 3) -> 1 
"Saturday"^match(6, "daytime", 1, 3) -> 1 
5.1.3.50. matchChar 

>>-matchChar (n,chars)------------------------- >< 


Returns .true ("1") if the character at position n matches any character of the string chars. Returns .false 
("0") if the character does not match any of the characters in the reference set. The argument n must be a 
positive whole number less than or equal to the length of the target string. 


Examples: 

"ac-b"^matchChar(2, "+-*/") -> 1 
"a-b"^matchChar(1, "+-*/") -> 0 
"Friday"^matchChar(3, "aeiou" -> 1 
"FRIDAY" ~matchChar(3, "aeiou" -> 0 
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5.1.3.51. max 


Returns the largest number from among the receiver and any arguments. The number that max returns is 
formatted according to the current NUMERIC settings. You can specify any number of numbers. 


Examples: 

12~max(6,7,9) -> 12 
17.37шах(19,17.03) -> 19 
"-T'"max("-3","-4,3") -> -3 


17шах(2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21) -> 21 


5.1.3.52. тіп 


Returns the smallest number from among the receiver and any arguments. The number that min returns 
is formatted according to the current NUMERIC settings. You can specify any number of numbers. 


Examples: 

12^min(6,7,9) -> 6 
17.37шіп(19,17.03) -> 17.03 
"-T"TMIN("-3","-4,.3") -> -7 
21~min(20,19,18,17,16,15,14,13,12,11,10,9,8,7,6,5,4,3,2,1) -> 1 


5.1.3.53. overlay 


»»-overlay (new-*--------------------------------------- %-)----- >< 
%-,--%---%--%------------------------- +-+ 


ЕД 
%-п-%  t-,--4--------4--4------4- 
*t-length-* +-,pad-+ 


Returns a copy of the receiving string, which, starting at the nth character, is overlaid with the string new, 
padded or truncated to length /ength. The overlay can extend beyond the end of the receiving string. If 
you specify length, it must be a positive whole number or zero. The default value for length is the length 
of new. If n is greater than the length of the receiving string, padding is added before the new string. The 
default pad character is a blank, and the default value for n is 1. If you specify n, it must be a positive 
whole number. 


Examples: 


"abcdef"^overlay(" ",3) -> "ар def" 
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"abcdef"^overlay(".",3,2) -> "ар. ef" 
"abcd" “overlay ("qq") -> "адаса" 
"abcd" отегтау ("аа",4) -> "abcqq" 
"abc" “overlay ("123",5,6,"+") => "арс+123+++" 


5.1.3.54. роѕ 


>>-pos (needle-4--------------------------- %-)--->< 
%-,--%------- %--%--------- +-+ 


, 
*t-start-* +-,length-+ 


Returns the position in the receiving string of another string, needle. (See also lastPos.) It returns 0 if 
needle is the null string or is not found or if start is greater than the length of the receiving string. By 
default, the search starts at the first character of the receiving string (that is, the value of start is 1), and 
continues to the end of the string. You can override this by specifying start, the point at which the search 
starts, and length, the bounding limit for the search. If specified, start must be a positive whole number 
and length must be a non-negative whole number. 


Examples: 

"Saturday"^pos("day") -> 6 

"арс def ghi"~pos("x") -> 0 

"арс def ghi"~pos(" ") -> 4 

"abc def ghi"~pos(" ",5) -> 8 

"abc def ghi"^pos(" ",5,3) -> 0 

5.1.3.55. replaceAt 

>>-replaceAt (new,n,length-4*------ %-)----- >< 
+-,pad-+ 


Returns a copy of the receiving string, with the characters from the nth character for length characters 
replaced with new. The replacement position and length can extend beyond the end of the receiving 
string. The starting position, п, must be a positive whole number, and the length must be a positive whole 
number or zero. If n is greater than the length of the receiving string, padding is added before the new 
string. The default pad character is a blank. 


Examples: 

"abcdef"^replaceAt(" ",3, 1) -» "ab def" 
"abcdef"^replaceAt(" ",3, 3) -> "ap f" 
"abc"^replaceAt("123",5,6,"4") -> "арс+123" 


5.1.3.56. reverse 


?2-тепагве-----<--- тт 99 ------------------- >< 


Returns a copy of the receiving string reversed. 
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Examples: 
"ABc."” reverse -> ".cBA" 
"XYZ "^reverse -> " ZYX" 


5.1.3.57. right 


>>-right (length-4------ %-)------------------------------------- >< 
+-,pad-+ 


Returns a string of length length containing the rightmost length characters of the receiving string. The 
string returned is padded with pad characters, or truncated, on the left as needed. The default pad 
character is a blank. The length must be a positive whole number or zero. 


Examples: 

"abc d'^right(8) -> " abc d" 

"abc def"^right(5) -> "с def" 

"12"^right(5,"0") -> "00012" 

5.1.3.58. sign 

ak aa Saa >< 


Returns a number that indicates the sign of the receiving string, which is a number. The receiving string 
is first rounded according to standard Rexx rules, as though the operation receiving_string+0 had been 
carried out. It returns -1 if the receiving string is less than 0, 0 if it is 0, and 1 if itis greater than 0. 


Examples: 

"12.3"^sign -> 1 
" -0.307"^sign -> -1 
0.0^sign -> 0 


5.1.3.59. space 


>>-врасе-%--------------- mri re rin re eo ақ мсек тг ісек кілдік ee pe >< 
+-(а-+------+-)-+ 
+-,pad-+ 


Returns a copy of receiving string, with n pad characters between each whitespace-delimited word. If 
you specify n, it must be a positive whole number or zero. If it is 0, all whitespace characters are 
removed. Leading and trailing whitespace characters are always removed. The default for n is 1, and the 
default pad character is a blank. 


Examples: 
"abc def "^space -> "арс def" 
" abc def"^space(3) -» "abc def" 
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"abc def "^space(1) -> "арс def" 

"abc def "^space(0) -» "abcdef" 

"abc def "^space(2,"-*") -> "abcttdef" 

5.1.3.60. strip 

SS SOLI p tr eee на +--------++<---<-----<« >< 
+-(option-+-------+-)-+ 


+- сраг-+ 


Returns а copy of the receiving string with leading characters, trailing characters, or both, removed, 
based on the option you specify. The following are valid options. (You need to specify only the first 
capitalized letter; all characters following it are ignored.) 


Both 


Removes both leading and trailing characters. This is the default. 


Leading 


Removes leading characters. 


Trailing 
Removes trailing characters. 


The char specifies the character to be removed, and the default is a blank. If you specify char, it must be 
exactly one character long. 


Examples: 

" abc "strip -> "ab c" 
"abc "“strip("L") -> "abc " 
" abc "^strip("t") -> "зар е" 
"12.7000"~strip(,0) -> "32: [^ 
"0012.700"^strip(,0) -> "12.7" 


5.1.3.61. subchar 


»»-subchar(n)---------------------------------------------- >< 


Returns the n’th character of the receiving string. n must be a positive whole number. If n is greater that 
the length of the receiving string then a zero-length string is returned. 


5.1.3.62. substr 


»»-substr(n-*------------------------- %-)---------------------- >< 
%-,--%--------4--%------4-% 
+-length-+ +-,pad-+ 
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Returns the substring of the receiving string that begins at the nth character and is of length length, 
padded with pad if necessary. The n must be a positive whole number. If n is greater than 
receiving string" length, only pad characters are returned. 


If you omit length, the rest of the string is returned. The default pad character is a blank. 


Examples: 

"abc"^substr(2) -» "bc" 
"abc"^substr(2,4) -> "bc " 
"abc"^substr(2,6,".") -» "be..." 


Note: In some situations the positional (numeric) patterns of parsing templates are more convenient 
for selecting substrings, in particular if you need to extract more than one substring from a string. 
See also left and right. 


5.1.3.63. subWord 


»»-subWord(n-4--------- %-)------------------------------------- >< 
+-,length-+ 


Returns the substring of the receiving string that starts at the nth word and is up to length blank-delimited 
words. The n must be a positive whole number. If you omit length, it defaults to the number of remaining 
words in the receiving string. The returned string never has leading or trailing whitespace, but includes 
all whitespace characters between the selected words. 


Examples: 
"Now is the time"~subWord (2,2) -> "is the" 
"Now is the time"^subWord(3) -> "the time" 
"Now is the time"^subWord(5) -> wn 
5.1.3.64. translate 
J>=trans latestsssS ssa ssas SSS SS se SRS SS SSS SRS SSR SS SSSR SSS SS SRS RSE SSS SER RRR SSS нн - += 
>< 
%-(---------------------------------------- %-%----------------------- +-)-+ 
+-tableo--+------------------------- +-+ +-,--+---+--+---------+-+ 
+- --+--------+--+------+-+ +-n-+ +-,length-+ 


+-tablei-+ +-,pad-+ 
Returns a copy of the receiving string with each character translated to another character or unchanged. 
You can also use this method to reorder the characters in the output table. (See last example) 


The output table is tableo and the input translation table is tablei. translate searches tablei for each 
character in the receiving string. If the character is found, the corresponding character in tableo is used in 
the result string. If there are duplicates in tablei, the first (leftmost) occurrence is used. If the character is 
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not found, the original character in the receiving string is used. The result string is always of the same 
length as the receiving string. 


The tables can be of any length. If you specify neither translation table and omit pad, the receiving string 
is translated to uppercase (that is, lowercase a-z to uppercase А-7), but if you include pad the entire string 
is translated to pad characters. tablei defaults to XRANGE("00"x,"FF"x), and tableo defaults to the null 
string and is padded with pad or truncated as necessary. The default pad is a blank. 


n is the position of the first character of the translated range. The default starting position is 1. length is 
the range of characters to be translated. If omitted, length remainder of the string from the starting 
position to the end is used. 


Examples: 

"abcdef"~translate -> "ABCDEF" 
"abcdef"^translate(, , , 3, 2) -> "abCDef" 
"abcdef"^translate("12", "ec") -> "ab2d1f" 
"abcdef"^translate("12", "abcd", ".") -> "32. ef" 
"APQRV"^translate(, "PR") -> "A Q V" 
"APQRV"^translate(XRANGE("OO"X, "Q")) -> "Ард " 
"4123"^translate("abcd", "1234") -> "dabc" 
"4123"^translate("abcd", "1234", , 2, 2) -> "да!" 


Note: The last example shows how to use the translate method to reorder the characters in a string. 
In the example, the last character of any 4-character string specified as the first argument would be 
moved to the beginning of the string. 


5.1.3.65. trunc 


22-2trunc-t----- ааа >< 
+- (п) -+ 


Returns the integer part the receiving string, which is a number, and и decimal places. The default n is 0 
and returns an integer with no decimal point. If you specify n, it must be a positive whole number or 
Zero. The receiving string is first rounded according to standard Rexx rules, as though the operation 
receiving string*O had been carried out. This number is then truncated to n decimal places or trailing 
zeros are added if needed to reach the specified length. The result is never in exponential form. If there 
are no nonzero digits in the result, any minus sign is removed. 


Examples: 

12.3^trunc -> 12 

127 .09782~trunc (3) -> 127.097 
127 .1~trunc (3) -> 127.100 
127~trunc (2) -> 127.00 


Note: The number is rounded according to the current setting of NUMERIC DIGITS if necessary, 
before the method processes it. 
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5.1.3.66. upper 


»»-upper(4---4--4--------- %---)---------------------- >< 
%-п-% +-,length-+ 


Returns а new string with the characters of the target string beginning with character n for length 
characters converted to uppercase. If n is specified, it must be a positive whole number. If n is not 
specified, the case conversion will start with the first character. If length is specified, it must be a 

non-negative whole number. If length the default is to convert the remainder of the string. 


Examples: 
"Albert Einstein"^upper -> "ALBERT EINSTEIN" 
"abcdef"^upper(4) -> "abcDEF" 
"abcdef"^upper(3,2) -> "abCDef" 
5.1.3.67. verify 
»»-verify (reference-4---------------------------------------------- %-)-->< 
%-,--%-------- %--%--------------------------- +-+ 
t option t а, т-фонеснеа %--%--------- +-+ 


*-start-* +-,length-+ 


Returns a number that, by default, indicates whether the receiving string is composed only of characters 
from reference. It returns 0 if all characters in the receiving string are in reference or returns the position 
of the first character in the receiving string not in reference. 


The option can be either Nomatch (the default) or Match. (You need to specify only the first capitalized 
and highlighted letter; all characters following the first character are ignored) 


If you specify Match, the method returns the position of the first character in the receiving string that is in 
reference, or returns 0 if none of the characters are found. 


The default for start is 1. Thus, the search starts at the first character of the receiving string. You can 
override this by specifying a different start point, which must be a positive whole number. 


The default for length is the length of the string from start to the end of the string. Thus, the search 
proceeds to the end of the receiving string. You can override this by specifying a different length, which 
must be a non-negative whole number. 


If the receiving string is null, the method returns 0, regardless of the value of the option. Similarly, if 
start is greater than receiving string" length, the method returns 0. If reference is null, the method 
returns 0 if you specify Match. Otherwise, the method returns the start value. 


Examples: 

"123"^verify ("1234567890") -> 0 
"1Z3"~verify ("1234567890") -> 2 
"АВАТ""уегіҒу("1234567890") -> 1 
" ABAT"^verify("1234567890","M") -> 3 
"ABAT"^verify("1234567890","N") -> 1 
"1P3Q4"^verify("1234567890", ,3) -> 4 
"123"^verify("",N,2) -> 2 
"ABCDE"^verify("", ,3) -> 3 
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"AB3CD5"^verify("1234567890","M",4) -> 6 
"ABCDEF"^verify("ABC","N",2,3) -> 4 
"“ABCDEF"~verify("ADEF" ,"M",2,3) -> 4 

5.1.3.68. word 
>>-чога(һ)----------------------------------------------------- >< 


Returns the nth whitespace-delimited word in the receiving string or the null string if the receiving string 
has fewer than n words. The n must be a positive whole number. This method is exactly equivalent to 


receiving string^subWord(n,1). 


Examples: 

"Now is the time"^word(3) -> "the" 

"Now is the time"~word(5) -» mu 

5.1.3.69. wordlndex 
»»-wordIndex(n)------------------------------------------------ >< 


Returns the position of the first character in the nth whitespace-delimited word in the receiving string. It 
returns 0 if the receiving string has fewer than n words. The n must be a positive whole number. 


Examples: 

"Now is the time"^wordIndex(3) -> 8 

"Now is the time"~wordIndex (6) -> 0 

5.1.3.70. wordLength 
»»-wordLength(n)----------------------------------------------- >< 


Returns the length of the nth whitespace-delimited word in the receiving string or 0 if the receiving string 
has fewer than n words. The и must be a positive whole number. 


Examples: 

"Now is the time"^wordLength(2) -> 2 

"Now comes the time"~wordLength (2) -> 5 

"Now is the time"~wordLength(6) -» 0 

5.1.3.71. wordPos 

»»-wordPos(phrase-4-------- pejse E >< 


+-,start-+ 
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Returns the word number of the first word of phrase found in the receiving string, or 0 if phrase contains 
no words or if phrase is not found. Several whitespace characters between words in either phrase or the 
receiving string are treated as a single blank for the comparison, but, otherwise, the words must match 
exactly. 


By default the search starts at the first word in the receiving string. You can override this by specifying 
start (which must be positive), the word at which the search is to be started. 


Examples: 

"now is the time"^wordPos("the") -> 3 

"now is the time"^wordPos("The") -> 0 

"now is the time"^wordPos("is the") -> 2 

"now is the time"^wordPos("is the") -> 2 

"now is the time"^wordPos("is time ") -> 0 

"To be or not to be"^wordPos("be") -> 2 

"To be or not to be"^wordPos("be",3) -> 6 

5.1.3.72. words 

>>погдв-----------+- те ----------------------+-+-----+ >< 


Returns Ше number of whitespace-delimited words in Ше receiving string. 


Examples: 

"Now is the time"~words -> 4 

" "words -> 0 

5.1.3.73. x2b 
>>-х2р--------------------------------------------------------- >< 


Returns a string, іп character format, that represents the receiving string, which is а string of hexadecimal 
characters converted to binary. The receiving string can be of any length. Each hexadecimal character is 
converted to a string of 4 binary digits. The receiving string can optionally include whitespace characters 
(at byte boundaries only, not leading or trailing) to improve readability; they are ignored. 


The returned string has a length that is a multiple of four, and does not include any whitespace. 


If the receiving string is null, the method returns a null string. 


Examples: 

"C3"^x2b -» "11000011" 
"T"7x2b -> "0111" 

"1 Ci"^x2b -» "000111000001" 


You can combine x2b with the methods d2x and c2x to convert numbers or character strings into binary 
form. 


Examples: 
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"O3"x^c2x^x2b -> "11000011" 
"129"^d2x^x2b -> "10000001" 
"12""d2x^x2b -> "1100" 


5.1.3.74. x2c 


Returns a string, in character format, that represents the receiving string, which is a hexadecimal string 
converted to character. The returned string is half as many bytes as the receiving string. The receiving 
string can be any length. If necessary, it is padded with a leading 0 to make an even number of 
hexadecimal digits. 


You can optionally include whitespace in the receiving string (at byte boundaries only, not leading or 
trailing) to improve readability; they are ignored. 


If the receiving string is null, the method returns a null string. 


Examples: 


"4865 6c6c 6f"^x2c -> "Hello" /* ASCII */ 
"3732 73"~x2c -> "728" /* ASCII */ 


5.1.3.75. x2d 


>>-х24-+----- %------------------------------------------------- >< 
+-(n)-+ 


Returns the decimal representation of the receiving string, which is a string of hexadecimal characters. If 
the result cannot be expressed as a whole number, an error results. That is, the result must not have more 
digits than the current setting of NUMERIC DIGITS. 


You can optionally include whitespace characters in the receiving string (at byte boundaries only, not 
leading or trailing) to improve readability; they are ignored. 


If the receiving string is null, the method returns 0. 


If you do not specify n, the receiving string is processed as an unsigned binary number. 


Examples: 

"OE"^x2d -> 14 

"81"^x2d -> 129 

"F81"^x2d -> 3969 

"FF81"^x2d -> 65409 

"46 30"X^x2d -> 240 /ж ASCII */ 
"66 30"X^x2d -> 240 /* ASCII */ 


If you specify n, the receiving string is taken as a signed number expressed in n hexadecimal digits. If the 
leftmost bit is off, then the number is positive; otherwise, it is a negative number. In both cases it is 
converted to a whole number, which can be negative. If n is 0, the method returns 0. 
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If necessary, the receiving string is padded on the left with 0 characters (note, not "sign-extended"), or 
truncated on the left to n characters. 


Examples: 

"81"~x2d (2) -> 
"81"~x2d (4) -> 
"FO81"~x2d (4) -> 
"FO81"~x2d(3) -> 
"Е081"7х24 (2) -> 
"Е081"7х24 (1) -> 
"0031 "7х24 (0) -> 


-127 
129 
-3967 
129 
-127 


5.1.4. Тһе Method Class 


Тһе Method class creates method objects from Rexx source code. It is а subclass of the Object class. 


Figure 5-4. The Method class and methods 
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Note: The Method class also has available class methods that its metaclass, the Class class, 


defines. 
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5.1.4.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) — instanceMethod send 


=\===\== <> >< instanceMethods sendWith 
class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


5.1.4.2. new (Class Method) 


>>-пеи(паше,зойгсе--+------------- %---)------------------- >< 
+--, context--+ 


Returns a new instance of method class, which is an executable representation of the code contained іп 
the source. The name is a string. The source can be a single string or an array of strings containing 
individual method lines. 


The context allows the created method to inherit class and routine lookup scope from another source. If 
specified, context can be a Method object, a Routine object, a Package object, or the string 
"PROGRAMSCOPE". PROGRAMSCOPE is the default, and specifies that the newly created method 
will inherit the class and routine search scope from the caller of new method. 


5.1.4.3. newFile (Class Method) 
»»-newFile(filename)------------------------------------------- >< 


Returns a new instance of method class, which is an executable representation of the code contained in 
the file filename. The filename is a string. 


5.1.4.4. loadExternalMethod (Class Method) 
>>-loadExternalMethod (name ,descriptor) ------------------------ >< 


Resolves a native method in an external library package and returns a Method object instance that can 
used to call the external method. The descriptor is a string containing blank-delimited tokens that 
identify the location of the native method. function. The first token identifies the type of native function 
and must be "LIBRARY". The second token must identify the name of the external library. The external 
library is located using platform-specific mechanisms for loading libraries. For Unix-based systems, the 
library name is case-sensitive. The third token is optional and specifies the name of the method within 
the library package. If not specified, name is used. The method name is not case sensitive. If the target 
method cannot be resolved, .nil is returned. 
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Example: 


method = .Method~loadExternalMethod("homeAddress=", ?LIBRARY mylib setHomeAddress’ ) 


5.1.4.5. isGuarded 


>> -1вбпагдед----------------+-------- << <-- >< 


Returns true ("1") if the method is a Guarded method. Returns false ("0") for Unguarded methods. 


5.1.4.6. isPrivate 


>2-1вРелтае------------ ----------------- >< 


Returns true ("1") if the method is a Private method. Returns false ("0") for Public methods. See Public 
versus Private Methods for details on private method restrictions. 


5.1.4.7. isProtected 


>2-1вРгоресвед-------------------------+--+--+-+-<++ << >< 


Returns true ("1") if the method is a Protected method. Returns false ("0") for unprotected methods. 


5.1.4.8. package 


>> -раскаге----------------- ese - --- >< 


Returns Ше Package class instance that defined Ше method instance. The package instance controls and 
defines the search order for classes and routines referenced by the method code. 


5.1.4.9. setGuarded 


>> =set Guarded == SSS sss SSS SSS SSS SSS SS SSS SSeS Sasa ---< >< 


Specifies that the method is a guarded method that requires exclusive access to its scope variable pool to 
run. If the receiver is already guarded, a setGuarded message has no effect. Guarded is the default state 
for method objects. 


5.1.4.10. setPrivate 


>2-вевРгатаве----------------------------- << >< 


Specifies that a method is а private method. By default, method objects are created as public methods. 
See Public versus Private Methods for details on private method restrictions. 
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5.1.4.11. setProtected 
>2=веїрговесбей============5======3985===6=====н=н=еныенеБеееен >< 


Specifies that a method is а protected method. Method objects аге not protected by default. (See The 
Security Manager for details.) 


5.1.4.12. setSecurityManager 


2»-setS5ecurityManager--t----------occnc----ooo5es-- Ф=========== >< 
+-(security_manager_object)-+ 


Replaces the existing security manager with the specified security_manager_object. If 
security_manager_object is omitted, any existing security manager is removed. 


5.1.4.13. setUnguarded 


po-setUngpuarded sss se ssn assess Sasha Sr Saas S a Gene Snes a Saeaase >< 


Turns off the guard attribute of the method, allowing this method to run on an object even if another 
method has acquired exclusive access to the scope variable pool. Methods are unguarded by default. 


A guarded method can be active for an object only when no other method requiring exclusive access to 
the object’s variable pool is active in the same object. This restriction does not apply if an object sends 
itself a message to run a method and it already has exclusive use of the same object variable pool. In this 
case, the method runs immediately regardless of its guarded state. 


5.1.4.14. source 


>>-войгсе----------------------<-<<-<-- ee See >< 


Returns the method source code as a single-index array of source lines. If the source code is not 
available, source returns an array of zero items. 


5.1.5. The Routine Class 


The Routine class creates routine objects from Rexx source code. It is a subclass of the Object class. 
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Figure 5-5. The Routine class and methods 
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Note: The Routine class also has available class methods that its metaclass, the Class class, 
defines. 


5.1.5.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method)  instanceMethod send 


=\===\== <> >< instanceMethods sendWith 
class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


5.1.5.2. new (Class Method) 


>>-new (name , source--+------------- %---)------------------- >< 


+--, context--+ 


Returns a new instance of the routine class, which is an executable representation of the code contained 
in the source. The name is a string. The source can be a single string or an array of strings containing 
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individual method lines. 


The context allows the created routine to inherit class and routine lookup scope from another source. If 
specified, context can be a Method object, a Routine object, or a Package object. If not specified, the 
newly created method will inherit the class and routine search scope from the caller of new method. 


5.1.5.3. newFile (Class Method) 


»»-newFile(filename)------------------------------------------- >< 


Returns a new instance of the routine class, which is an executable representation of the code contained 
in the file filename. The filename is a string. 


5.1.5.4. loadExternalRoutine (Class method) 


>>-loadExternalRoutine (name,descriptor)------------------------ >< 


Resolves a native routine in an external library package and returns a Routine object instance that can 
used to call the external routine. The descriptor is a string containing blank-delimited tokens that 
identify the location of the native routine. function. The first token identifies the type of native routine 
and must be "LIBRARY". The second token must identify the name of the external library. The external 
library is located using platform-specific mechanisms for loading libraries. For Unix-based systems, the 
library name is case-sensitive. The third token is optional and specifies the name of the routine within the 
library package. If not specified, name is used. The routine name is not case sensitive. If the target 
routine cannot be resolved, .nil is returned. 


Example: 


routine = .Routine^loadExternalRoutine("Pi", "LIBRARY rxmath RxCalcPi") 


5.1.5.5. call 


>>-са11-%-------------------- Жа==езЕЕсн=еБе=авысысеесаазЕынаы=с=Ер >< 
| 
| 


+-(----агршеп-+--) -+ 


Calls Ше routine object using the provided arguments. The code in the routine object is called as if it was 
an external routine call. The return value will be any value returned by the executed routine. 


5.1.5.6. callWith 


»»-call(array)---------------------------------------------------- >< 


Calls the routine object using the arguments provided in array. Each element of array will be mapped to 
its corresponding call argument. The code in the routine object is called as if it was an external routine 
call. The return value will be any value returned by the executed routine. 


ooRexx Reference Version 4.0.0 171 


Chapter 5. The Builtin Classes 
5.1.5.7. package 
>>-раскаве-------н9----- ss SS Ses Sas eh Ser SaaS Se ree Sse Sessa easas >< 


Returns the Package class instance that defined the routine instance. The package instance controls and 
defines the search order for classes and routines referenced by the routine code. 


5.1.5.8. setSecurityManager 


2»-set5écurityManager--t----------oc5ns---ooooneus- Ф=========== >< 
+-(security_manager_object)-+ 


Replaces the existing security manager with the specified security_manager_object. If 
security_manager_object is omitted, any existing security manager is removed. 


5.1.5.9. source 


22 SOUL CCH as Sa ee a Se Se aaa et a He ee ee -9 >< 


Returns the routine source code as a single-index array of source lines. If the source code is not available, 
source returns an array of zero items. 


5.1.6. The Package Class 


The Package class contains the source code for a package of Rexx code. A package instance holds all of 
the routines, classes, and methods created from a source code unit and also manages external 
dependencies refereced by ::REQUIRES directives. The files loaded by ::REQUIRES are also contained 
in Package class instances. It is a subclass of the Object class. 
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Figure 5-6. The Package class and methods 
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Note: The Package class also has available class methods that its metaclass, the Class class, 


defines. 


5.1.6.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) — instanceMethod send 
=\= == \== <> >< instanceMethods sendWith 
class isA setMethod 


173 


Chapter 5. The Builtin Classes 


copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


5.1.6.2. new (Class Method) 


>>-new (name , source--+------------------ %---)------------------- >< 
%--, methodobject--+ 


Returns a new instance of the package class, which is a representation of the code contained in the 
source. The name is a string. The source can be a single string or an array of strings containing 
individual method lines. 


The third parameter influences the scope of the routine. If none is given, the program scope is used. If 
another method or routine object is specified, the scope of the provided method or routine is used. 


5.1.6.3. newFile (Class Method) 


»»-newFile(filename)------------------------------------------- >< 


Returns a new instance of the package class, which is an executable representation of the code contained 
in the file filename. The filename is a string. 


5.1.6.4. addClass 


>>-addClass (name,class)---------------------------------------- >< 


Adds the class object class to the available classes under the name name. This is added to the package as 
a non-public class. 


5.1.6.5. addPackage 
>>-addPackage (package) ---------------------------------------- >< 


Adds the package object package to the dependent packages under the name name. The added package is 
processed as if it had been added using a :: REQUIRES directive in the original package source. 


5.1.6.6. addPublicClass 


>>-addPublicClass (name,class)---------------------------------- >< 


Adds the class object class to the available public classes under the name name. This is added to the 
package as a public class. 
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5.1.6.7. addPublicRoutine 
>>-addPublicRoutine (name,routine)---------------------------------------- >< 


Adds the routine object routine to the available routines under the name name. This is added to the 
package as a public routine. 


5.1.6.8. addRoutine 


»»-addRoutine(name,routine)---------------------------------------- >< 


Adds the routine object routine to the available routines under the name name. This is added to the 
package as a non-public routine. 


5.1.6.9. classes 


POAC LASSOS SS Sasa SSSR SS HSS RRR SRS SSS SRS SSS aS Se --- eer >< 


Returns a directory containing all classes defined by this package or imported as public classes from 
another package. 


5.1.6.10. definedMethods 


>>-йеГіпваМебойв---------ə---------зак------ст-------әсек------- >< 


Returns а directory containing all unattached methods defined by this package. This is the same directory 
available to code within the package via the . METHODS environment symbol. 


5.1.6.11. digits 


>>-digits------------------------------------------------------ >< 


Returns the initial NUMERIC DIGITS setting used for all Rexx code contained within the package. The 
default value is 9. The ::OPTIONS directive can override the default value. 


5.1.6.12. findClass 


>>-findClass (name)--------------------------------------------- >< 


Performs the standard environment symbol searches given class name. The search is performed using the 
same search mechanism used for environment symbols or class names specified on ::CLASS directives. 
If the name is not found, .nil will be returned. 
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5.1.6.13. findRoutine 
>>-findRoutine (name)--------------------------------------------- >< 


Searches for a routine within the package search order. This includes ::ROUTINE directives within the 
package, public routines imported from other packages, or routines added using the addRoutine method. 
The argument name must be a string object. If the name is not found, .nil will be returned. 


5.1.6.14. form 


Returns the initial NUMERIC FORM setting used for all Rexx code contained within the package. The 
default value is SCIENTIFIC. The ::OPTIONS directive can override the default value. 


5.1.6.15. fuzz 


Returns the initial NUMERIC FUZZ setting used for all Rexx code contained within the package. The 
default value is 0. The ::OPTIONS directive can override the default value. 


5.1.6.16. importedClasses 


22-3mportedCLasses-—------——-——---————--- ecciesie >< 


Returns a directory containing all public classes imported from other packages. 


5.1.6.17. importedRoutines 


22-importedRoutines------—------------e-c----eceeceeenoe eer >< 


Returns a directory containing all public routines imported from other packages. 


5.1.6.18. loadLibrary 


>>-loadLibrary (name)----------------------------------------- >< 


Loads a native library package and adds it to the list of libraries loaded by the interpreter. The name 
identifies a native external library file that will be located and loaded as if it had been named on а 
zREQUIRES LIBRARY directive. If the library is successfully loaded, loadLibrary will return 1 (true), 
otherwise it returns O (false). 
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5.1.6.19. loadPackage 


>>-loadPackage (name-4--------- %-)---------------------------- >< 
+- „воцгсе-+ 


Loads a package and adds it to the list of packages loaded by Ше package manager. If only name is 
specified, name identifies a file that will be located and loaded as if it had been named on a ::REQUIRES 
directive. If source is given, it must be an array of strings that is the source for the loaded package. If a 
package name has already been loaded by the package manager, the previously loaded version will be 
use. The resolved package object will be added to the receiving package object’s dependent packages. 


5.1.6.20. name 


Returns the string name of the package. 


5.1.6.21. publicClasses 


2»-publicClasses-----------55------c9d--eopsoedoococ0- >< 


Returns a directory containing all public classes defined in this package. 


5.1.6.22. publicRoutines 


22-риБаскопвпез----------- + + <---- Sea >< 


Returns a directory containing all public routines defined in this package. 


5.1.6.23. routines 


>р-гощапев- 939 SRS н-- Tas SaaS >< 


Returns a directory containing all routines defined in this package. 


5.1.6.24. setSecurityManager 


»»-setSecurityManager--4--------------------------- RUE ELITR aa >< 
+-(security_manager_object)-+ 


Replaces the existing security manager with the specified security_manager_object. If 
security_manager_object is omitted, any existing security manager is removed. 
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5.1.6.25. source 
22 SOUL Ce aes aS aaa een eee eee 9 >< 


Returns the package source code as a single-index array of source lines. If the source code is not 
available, source returns an array of zero items. 


5.1.6.26. sourceLine 


»»-sourceline(n)------------------------------------------------------ >< 


Returns the nth source line from the package source. If the source code is not available or the indicated 
line does not exist, a null stirng is returned. 


5.1.6.27. sourceSize 


>>-вопгсебате----------- нея SSS SSNS SS SS SSSR SRS SRS SS SSE creen >< 


Returns the size of the source code for the package object. If the source code is not available, 0 is 
returned. 


5.1.6.28. trace 


22 =CLAGC seam sa es gt ee ee ee ee eee >< 


Returns the initial TRACE setting used for all Rexx code contained within the package. The default 
value is Normal. The ::OPTIONS directive can override the default value. 


5.1.7. The Message Class 


A message object provides for the deferred or asynchronous sending of a message. You can create a 
message object by using the new method of the Message class or the start method of the Object class. 
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Figure 5-7. The Message class and methods 
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Note: The Message class also has available class methods that its metaclass, the Class class, 
defines. 


5.1.7.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) instanceMethod send 


= \= == \== <> >< instanceMethods sendWith 
class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


5.1.7.2. new (Class Method) 


| %--------------- + 
| ү | 
++, Individual---+----------- +-+- 


»»-new(target,messagename-4------------------------------- %-)-->< 
| 
| 
| +-,argument-+ | 
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*t-,Àrray,argument--------------- + 


Initializes the message object for sending the message name messagename to object target. 


The messagename can be a string or an array. If messagename is an array object, its first item is the name 
of the message and its second item is a class object to use as the starting point for the method search. For 
more information, see Classes and Inheritance. 


If you specify the Individual or Array option, any remaining arguments are arguments for the message. 
(You need to specify only the first letter; all characters following the first are ignored.) 


Individual 


If you specify this option, specifying argument is optional. Any arguments are passed as message 
arguments to target in the order you specify them. 


Array 


If you specify this option, you must specify an argument, which is an array object. (See The Array 
Class.) The member items of the array are passed to target as arguments. The first argument is at 
index 1, the second argument at index 2, and so on. If you omitted any indexes when creating the 
array, the corresponding message arguments are also omitted. 


If you specify neither Individual nor Array, the message sent has no arguments. 


Note: This method does not send the message messagename to object target. The SEND or 
START method (described later) sends the message. 


5.1.7.3. arguments 


22-агришпепъв------------ 3 te << ++ >< 


Returns ап array of argument objects used to invoke Ше message. 


5.1.7.4. completed 


>>-сопревед------------##95 ня SS a Se Se SS SRS SS -- ен -- 5 >< 


Returns 1 if the message object has completed executing its message, or 0. You can use this method to 
test for completion as an alternative to calling result and waiting for the message to complete. 


5.1.7.5. errorCondition 
>>-аггогбопд1Ълоп--------- 99 -----5-5--------#------#-+------ >< 


Returns an error condition object from any execution error with Ше message object’s message invocation. 
If the message completed normally, or is still executing, errorCondition returns the Nil object. 
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5.1.7.6. hasError 


>>-ПавЕггог---------- as SaaS esse SSS cS +-----#+-8---+- >< 


Returns 1 if the message object’s message was terminated with an error condition. Returns 0 if the 
message has not completed or completed without error. 


5.1.7.7. messageName 


DP SMES SAG CNAM CH Ase sss eee SSeS ee >< 


Returns the string message name used to invoke a method. 


5.1.7.8. notify 


>>-notify (message)--------------------------------------------- >< 


Requests notification about the completion of processing of the message send or start. The message 
object message is sent as the notification. You can use notify to request any number of notifications. 

After the notification message, you can use the result method to obtain any result from the messages 
send or start. 


Example: 
/* Event-driven greetings */ 
. prompter~new~prompt (.nil) 
:class prompter 
::method prompt 
expose name 
use arg msg 
if msg \= .nil then do 
name = msg result 
if name = "quit" then return 
say "Hello," name 
end 


say 'Enter your name ("quit" to quit): 


/* Send the public default object .INPUT a LINEIN message asynchronously */ 
msg-.message^new(.input,"LINEIN")^^start 


/* Sends self^prompt(msg) when data available ж/ 
msg^notify(.message^new(self,"PROMPT","I",msg)) 


/* Don't leave until user has entered "quit" ж/ 
guard on when name="quit" 
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5.1.7.9. result 


>3-тев << --+- ae SSS tS SSS --------------------+- >< 


Returns the result of the message send or start. If message processing is not yet complete, this method 
waits until it completes. If the message send or start raises an error condition, this method also raises an 
error condition. 


Example: 


/* Example using result method */ 


string-"700" /* Create a new string object, string ж/ 
bond-string^start("reverse") /* Create a message object, bond, and ж/ 
/* start it. This sends a REVERSE ж/ 
/* message to string, giving bond ж/ 
/* the result. ж/ 


/* Ask bond for the result of the message */ 
say "The result of message was" bond^result /* Result is 007 ж/ 


5.1.7.10. send 


>>-вепд--+---------- he SS SSeS нЕ зе РЕНЕ нетен ара Sass SSeS >< 
*-(target)-* 


Returns the result (if any) of sending the message. If you specify target, this method sends the message 
to target. Otherwise, this method sends the message to the target you specified when the message object 
was created. send does not return until message processing is complete. 


You can use the notify method to request notification that message processing is complete. You can use 
the result method to obtain any result from the message. 


5.1.7.11. start 


2»-Start--r---------- ЕЕ ----------------------<+--- << >< 
+-(target)-+ 


Sends the message to start processing at a specific target whereas the sender continues processing. If you 
specify target, this method sends the message to target. Otherwise, this method sends the message to the 
target that you specified when the message object was created. This method returns as soon as possible 
and does not wait until message processing is complete. When message processing is complete, the 
message object retains any result and holds it until requested via the result method. You can use the 
notify method to request notification when message processing completes. 


5.1.7.12. Example 


/* Using Message class methods */ 
/* Note: In the following example, ::METHOD directives define class Testclass */ 
/* with method SHOWMSG ж/ 
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ez-.testclass^new /* Creates a new instance of Testclass */ 

mymsg-ez^start("SHOWMSG","Hello, Ollie!",5) /* Creates and starts ж/ 
/* message mymsg to send */ 
/* SHOWMSG to ez */ 

/* Continue with main processing while SHOWMSG runs concurrently ж/ 

do 5 

say "Hello, Stan!" 
end 
/* Get final result of the SHOWMSG method from the mymsg message object */ 


say mymsg result 
say "Goodbye, Stan..." 


exit 
::class testclass public /* Directive defines Testclass ж/ 
::method showmsg /* Directive creates new method SHOWMSG ж/ 
use arg text,reps /* class Testclass */ 
do reps 

say text 
end 


reply "Bye Bye, Ollie..." 
return 


The following output is possible: 








Hello, Ollie! 
Hello, Stan! 
Hello, Ollie! 
Hello, Stan! 
Hello, Ollie! 
Hello, Stan! 
Hello, Ollie! 
Hello, Stan! 
Hello, Ollie! 
Hello, Stan! 


Bye Bye, Ollie... 
Goodbye, Stan... 


5.1.7.13. target 
>2-рагребт-------2------+++-+-+---+-+----< ++ - er ee ee >< 


Returns the object that is the target of the invoked message. 
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5.2. The Stream Classes 


This section describes the Rexx classes which implement Rexx data streams. 


5.2.1. The InputStream Class 


This class is defined as an abstract mixin class. It must be implemented by subclassing it or inheriting 
from it as a mixin. Many of the methods in this class are abstract and must be overridden or they will 


throw a syntax error when invoked. 


Figure 5-8. The InputStream class and methods 





Object 


InputStream 


arrayIn 
сһагіп 
charOut 
chars 
close 
lineln 
lineOut 
lines 
open 
position 








Note: The InputStream class also has available class methods that its metaclass, the Class class, 


defines. 


5.2.1.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) — instanceMethod 


=\===\== <> >< instanceMethods 
class isA 

copy isInstanceOf 
defaultName objectName 
hasMethod objectName= 
identityHash Request 

init Run 


send 
sendWith 
setMethod 
Start 


startWith 
string 
unsetMethod 
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5.2.1.2. arrayln 


This is a default implementation of the arrayIn method using linein() method calls to fill the array. 


5.2.1.3. спайп 


This method is defined as an abstract method. Invoking it will cause syntax error 93.965 to be raised. 


5.2.1.4. charOut 


This is an unsupported operation for InputSteams. Invoking it will cause syntax error 93.963 to be raised. 


5.2.1.5. chars 


This method is defined as an abstract method. Invoking it will cause syntax error 93.965 to be raised. 


5.2.1.6. close 
This method is a NOP by default. 


5.2.1.7. lineln 


This method is defined as an abstract method. Invoking it will cause syntax error 93.965 to be raised. 


5.2.1.8. lineOut 


This is an unsupported operation for InputSteams. Invoking it will cause syntax error 93.963 to be raised. 


5.2.1.9. lines 


This method is defined as an abstract method. Invoking it will cause syntax error 93.965 to be raised. 


5.2.1.10. open 
This method is a NOP method. 


5.2.1.11. position 


This method is an optionally supported operation. By default, it will cause syntax error 93.963 to be 
raised. 
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5.2.2. The OutputStream Class 


This class is defined as an abstract mixin class. It must be implemented by subclassing it or inheriting 


from it as a mixin. Many of the methods in this class are abstract and must be overridden or they will 
throw a syntax error when invoked. 


Figure 5-9. The OutputStream class and methods 
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Note: The OutputStream class also has available class methods that its metaclass, the Class class, 
defines. 


5.2.2.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) instanceMethod send 


=\===\== <> >< instanceMethods sendWith 
class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


5.2.2.2. arrayOut 


This method is a default arrayOut implementation that writes all lines to the stream using lineout. 
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5.2.2.3. спайп 


This is an unsupported operation for OutputSteams. Invoking it will cause syntax error 93.963 to be 
raised. 


5.2.2.4. charOut 


This method is defined as an abstract method. Invoking it will cause syntax error 93.965 to be raised. 


5.2.2.5. chars 


This is an unsupported operation for OutputSteams. Invoking it will cause syntax error 93.963 to be 
raised. 


5.2.2.6. close 
This method is a NOP by default. 


5.2.2.7. lineln 


This is an unsupported operation for OutputSteams. Invoking it will cause syntax error 93.963 to be 
raised. 


5.2.2.8. lineOut 


This method is defined as an abstract method. Invoking it will cause syntax error 93.965 to be raised. 


5.2.2.9. lines 


This is an unsupported operation for OutputSteams. Invoking it will cause syntax error 93.963 to be 
raised. 


5.2.2.10. open 
This method is a NOP by default. 


5.2.2.11. position 


This method is an optionally supported operation. By default, it will cause syntax error 93.963 to be 
raised. 
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5.2.3. The InputOutputStream Class 


This class is defined as an abstract mixin class. It must be implemented by subclassing it or inheriting 
from it as a mixin. Many of the methods in this class are abstract and must be overridden or they will 
throw a syntax error when invoked. 


Figure 5-10. The InputOutputStream class 
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InputOutputStream 
+ InputStream 
+ OutputStream 








Note: The InputOutputStream class also has available class methods that its metaclass, the Class 
class, defines. 


5.2.3.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) instanceMethod send 


=\===\== <> >< instanceMethods sendWith 
class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


Methods inherited from the InputStream class. 


Note: This class is searched second for inherited methods. 


arrayIn close open 
charIn | lineln position 
charOut lineOut 


chars lines 
Methods inherited from the OutputStream class. 


Note: This class is searched first for inherited methods. 
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arrayOut close open 
charIn lineIn position 


charOut  lineOut 
chars lines 


5.2.4. The Stream Class 


A stream object allows external communication from Rexx. (See Input and Output Streams for a 
discussion of Rexx input and output.) 


The Stream class is a subclass of the InputOutputStream class. 


Figure 5-11. The Stream class and methods 
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Note: The Stream class also has available class methods that its metaclass, the Class class, 
defines. It also inherits methods from the InputOutputStream class. 
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5.2.4.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) — instanceMethod 
= \= == \== <> >< instanceMethods 
class isA 

copy isInstanceOf 
defaultName objectName 
hasMethod objectName= 
identityHash Request 

init Run 


send 


sendWith 
setMethod 
Start 


startWith 
string 
unsetMethod 


Methods inherited from the InputStream class. 


Note: This class is searched second for inherited methods. 


arrayIn close open 
charIn — lineln position 


charOut lineOut 
chars lines 


Methods inherited from the OutputStream class. 


Note: This class is searched first for inherited methods. 


arrayOut close open 
charIn lineIn position 


charOut  lineOut 
chars lines 


5.2.4.2. new (Inherited Class Method) 


»»-new(name)--------------------------------------------------- 


Initializes a stream object for stream name, but does not open the stream. Returns the new stream object 


5.2.4.3. аггауіп 


+- (LINES) -+ 


2»-arrayIn--t--------- н------------<- --+------- >< 


+- (CHARS) -+ 


Returns a fixed array that contains the data of the stream in line or character format, starting from the 
current read position. The line format is the default. 


If you have used the charIn method, the first line can be a partial line. 
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5.2.4.4. arrayOut 


+-,--LINES-+ 
>>-arrayOut (аггау-+---------- %-)------------------------------- >< 
+-,--CHARS-+ 


Writes the data in array array to the stream. If LINES is specified, each element of the array is written 
using lineout(). If CHARS is specified, each element is written using charout(). The default method is 
LINES. 


5.2.4.5. спайп 


>>-charIn-+---------------------------- %----------------------- >< 
+-(-+-------+--+---------+-) -+ 
+-start-+ +-,length-+ 


Returns a string of up to length characters from the input stream. The stream advances advances the read 
pointer by the number of characters read. If you omit length, it defaults to 1. If you specify start, this 
positions the read pointer before reading. The start value must be a positve whole number within the 
bounds of the stream. If the value is not a positive whole number, a syntax condition is raised. When the 
value is past the end of the stream, the empty string is returned and the NOTREADY condition is raised. 
If the stream is not already open, the stream attempts to open for reading and writing. If that fails, the 
stream opens for input only. 


5.2.4.6. charOut 


22-charÜut-4-----—-------———————-eee eo lima ER MERE E M MEE >< 
+-(-+--------+--+--------+-)-+ 
+-string-+ +-,start-+ 


Returns the count of characters remaining after trying to write string to the output stream. The stream 
also advances the write pointer. 


The string can be the null string. In this case, charOut writes no characters to the stream and returns 0. If 
you omit string, charOut writes no characters to the stream and returns 0. The stream is also closed. 


If you specify start, this positions the write pointer before writing. If the stream is not already open, the 
stream attempts to open for reading and writing. If that fails, the stream opens for for output only. 


5.2.4.7. chars 


2 P= ChAT Be ee Sa >< 


Returns the total number of characters remaining in the input stream. The count includes any line 

separator characters, if these are defined for the stream. For persistent the count is the count of characters 
from the current read position. (See Input and Output Streams for a discussion of Rexx input and output.) 
The total number of characters remaining cannot be determined for some streams (for example, STDIN). 
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For these streams. the CHARS method returns 1 to indicate that data is present, or 0 if no data is present. 
For Windows devices, CHARS always returns 1. 


5.2.4.8. close 


Closes the stream. close returns READY: if closing the stream is successful, or an appropriate error 
message. If you have tried to close an unopened file, then the close method returns a null string (""). 


5.2.4.9. command 


>>-сошпала(в%геаш command)------------------------------------- >< 


Returns a string after performing the specified stream_command. The returned string depends on the 
stream_command performed and can be the null string. The following stream_commands: 


* Open a stream for reading, writing, or both 

* Close a stream at the end of an operation 

* Move the line read or write position within a persistent stream (for example, a file) 
* Getinformation about a stream 


If the method is unsuccessful, it returns an error message string in the same form that the description 
method uses. 


For most error conditions, the additional information is in the form of a numeric return code. This return 
code is the value of ERRNO that is set whenever one of the file system primitives returns with a -1. 


5.2.4.9.1. Command Strings 


The argument stream. command can be any expression that to one of the following command strings: 


*-BOTH--| Write Options |-+ 


>>-%-ОРЕМ---------------------------- %--%------------- +-+------ >< 

| *-READ-------------------- + +-| Options |-+ | 
| *-WRITE--4--------- %------ + | 
| +-APPEND--+ | 
| +-REPLACE-+ | 
*-CLOSE---------------------------------------------- * 
+-FLUSH---------------------------------------------- + 
| +- = -+ +-CHAR-+ | 
%-%-5ЕЕК----- %--%----- +-offset--+------- %--%------ +--+ 
| +-POSITION-+ +- < -+ +-READ--+ +-LINE-+ | 
| +- + + +-WRITE-+ | 
| tS Sr | 
+-QUERY--+-DATETIME-------------------------- %------- + 

*-EXISTS---------------------------- * 

*-HANDLE---------------------------- * 

| +-CHAR-+ | 
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+-+-SEEK-----+--+-READ--+------+--+-+ 
| +-POSITION-+ | +-LINE-+ | | 
| | +-CHAR-+ | | 
| *-WRITE--*------ +-+ | 
| | +-LINE-+ | | 
| %-5Ү5------------- + | 
%-5І2Е------------------------------ + 
*-STREAMTYPE------------------------ * 
*-TIMESTAMP------------------------- * 
Write Options: 
| --4--------- %-------------------------------------------------- 
+-APPEND--+ 
+-REPLACE-+ 
Options: 
%----------------------------------- + 
V | 
[-=#-=======-=== +----+-NOBUFFER---------------------- i 
+-SHARED----- + +-BINARY--+------------------- +-+ 
+-SHAREREAD--+ +-RECLENGTH--length-+ 


+-SHAREWRITE-+ 


OPEN 


Opens the stream object and returns READY:. (If unsuccessful, the previous information about return 
codes applies.) The default for OPEN is to open the stream for both reading and writing data, for 
example: 'OPEN BOTH'. To specify that the stream be only opened for input or output, add READ or 
WRITE, to the command string. 


The following is a description of the options for OPEN: 


READ 


Opens the stream only for reading. 


WRITE 


Opens the stream only for writing. 


BOTH 
Opens the stream for both reading and writing. (This is the default.) The stream maintains 


separate read and write pointers. 


APPEND 


Positions the write pointer at the end of the stream. The write pointer cannot be moved 
anywhere within the extent of the file as it existed when the file was opened. 
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REPLACE 
Sets the write pointer to the beginning of the stream and truncates the file. In other words, this 
option deletes all data that was in the stream when opened. 

SHARED 


Enables another process to work with the stream in a shared mode. This mode must be 
compatible with the shared mode (SHARED, SHAREREAD, or SHAREWRITE) used by the 
process that opened the stream. 


SHAREREAD 


Enables another process to read the stream in a shared mode. 


SHAREWRITE 


Enables another process to write the stream in a shared mode. 


NOBUFFER 


Turns off buffering of the stream. All data written to the stream is flushed immediately to the 
operating system for writing. This option can have a severe impact on output performance. Use 
it only when data integrity is a concern, or to force interleaved output to a stream to appear in 
the exact order in which it was written. 


BINARY 


Opens the stream in binary mode. This means that line end characters are ignored; they are 
treated like any other byte of data. This is intended to process binary data using the line 
operations. 


Note: Specifying the BINARY option for a stream that does not exist but is opened for 
writing also requires the RECLENGTH option to be specified. Omitting the RECLENGTH 
option in this case raises an error condition. 


RECLENGTH length 


Allows the specification of an exact length for each line in a stream. This allows line operations 
on binary-mode streams to operate on individual fixed-length records. Without this option, line 
operations on binary-mode files operate on the entire file (for example, as if you specified the 
RECLENGTH option with a length equal to that of the file). The length must be 1 or greater. 


Examples: 


stream_name~ command ("open") 
stream_name~command("open write") 
stream_name~command("open read") 
stream_name~command("open read shared") 
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CLOSE 


closes the stream object. The COMMAND method with the CLOSE option returns READY: if the 
stream is successfully closed or an appropriate error message otherwise. If an attempt to close an 
unopened file occurs, then the COMMAND method with the CLOSE option returns a null string 


(" ". 
FLUSH 


forces any data currently buffered for writing to be written to this stream. 


SEEK offset 


sets the read or write position to a given number (offset) within a persistent stream. If the stream is 
open for both reading and writing and you do not specify READ or WRITE, both the read and write 
positions are set. 


Note: See Input and Output Streams for a discussion of read and write positions in a persistent 
stream. 


To use this command, you must first open the stream (with the OPEN stream command described 
previously or implicitly with an input or output operation). One of the following characters can 
precede the offset number. 


explicitly specifies the offset from the beginning of the stream. This is the default if you supply 
no prefix. For example, an offset of 1 with the LINE option means the beginning of the stream. 


specifies offset from the end of the stream. 


specifies offset forward from the current read or write position. 


specifies offset backward from the current read or write position. 


The command method with the SEEK option returns the new position in the stream if the read or 
write position is successfully located, or an appropriate error message. 


The following is a description of the options for SEEK: 


READ 


specifies that this command sets the read position. 


WRITE 


specifies that this command sets the write position. 
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CHAR 


specifies the positioning in terms of characters. This is the default. 


LINE 


specifies the positioning in terms of lines. For non-binary streams, this is potentially an 
operation that can take a long time to complete because, in most cases, the file must be scanned 
from the top to count the line-end characters. However, for binary streams with a specified 
record length, the new resulting line number is simply multiplied by the record length before 
character positioning. See Line versus Character Positioning for a detailed discussion of this 
issue. 


Note: If you do line positioning in a file open only for writing, you receive an error message. 


Examples: 


stream name^command("seek -2 read") 

Stream name^command("seek +15 read") 

Stream name^command("seek -7 write line") 

fromend = 125 

stream_name~command("seek <"fromend read) 
POSITION 

is a synonym for SEEK. 


Used with these stream_commands, the COMMAND method returns specific information about a 

stream. Except for QUERY HANDLE and QUERY POSITION, the stream returns the query 

information even if the stream is not open. The stream returns the null string for nonexistent streams. 
QUERY DATETIME 

Returns the date and time stamps of a stream in US format. For example: 

stream_name~command("query datetime") 


A sample output might be: 
11-12-95 03:29:12 


QUERY EXISTS 


Returns the full path specification of the stream object, if it exists, or a null string. For example: 


stream_name~command("query exists") 
A sample output might be: 
c:\data\file.txt 

QUERY HANDLE 


Returns the handle associated with the open stream. For example: 


stream_name~command("query handle") 
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A sample output might be: 3 


QUERY POSITION 


Returns the current read or write position for the stream, as qualified by the following options: 


READ 


Returns the current read position. 
WRITE 
Returns the current write position. 


Note: If the stream is open for both reading and writing, this returns the read position by default. 
Otherwise, this returns the appropriate position by default. 


CHAR 


Returns the position in terms of characters. This is the default. 


LINE 


Returns the position in terms of lines. For non-binary streams, this operation can take a long 
time to complete. This is because the language processor starts tracking the current line 
number if not already doing so, and, thus, might require a scan of the stream from the top to 
count the line-end characters. See Line versus Character Positioning for a detailed discussion 
of this issue. For example: 


stream_name~command("query position write") 


A sample output might be: 
247 


SYS 


Returns the operating system stream position in terms of characters. 


QUERY SEEK 
Is a synonym for QUERY POSITION. 


QUERY SIZE 
Returns the size, in bytes, of a persistent stream. For example: 
stream_name~command("query size") 
A sample output might be: 
1305 
QUERY STREAMTYPE 


Returns a string indicating whether the stream is PERSISTENT, TRANSIENT, or UNKNOWN. 
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QUERY TIMESTAMP 


Returns the date and time stamps of a persistent stream in an international format. This is the 
preferred method of getting date and time because it provides the full 4-digit year. For example: 


stream_name~command("query timestamp") 
A sample output might be: 


1995-11-12 03:29:12 


5.2.4.10. description 


>>-девстіркібі--егес---- аз атса E >< 


Returns any descriptive string associated with the current state of the stream or the Nil object if no 
descriptive string is available. The description method is identical with the STATE method except that 
the string that description returns is followed by a colon and, if available, additional information about 
ERROR or NOTREADY states. 


5.2.4.11. flush 


2? = ҢІС гімені екісі тесі S SSS ees ToS ee aS >< 


Returns READY:. It forces the stream to write any buffered data to the output stream. 


5.2.4.12. init 


>>-іпії (name)----------------------------------------------- >< 


Initializes a stream object defined by name. 


5.2.4.13. lineln 


»»-lineIn-4------------------------- антена Яне НЕ >< 
+-(-+------+-+--------+-) -+ 


+-line-+ +-,count-+ 


Returns the next count lines. The count must be 0 or 1. The stream advances the read pointer. If you omit 
count, it defaults to 1. A line number may be given to set the read position to the start of a specified line. 
This line number must be positive and within the bounds of the stream, and must not be specified for a 
transient stream. A value of 1 for line refers to the first line in the stream. If the stream is not already 
open, the it tries to open the stream for reading and writing. If that fails, the stream is opened for input 
only. 
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5.2.4.14. lineOut 


22-IineÜut-t-------------—---59-----—-9- +--------------------- >< 
+-(-+--------+-+-------+-)-+ 


+-string-+ +-,line-+ 


Returns 0 if successful in writing string to the output stream or 1 if an error occurs while writing the line. 
The stream advances the write pointer. If you omit string, the stream is closed. If you specify line, this 
positions the write pointer before writing. If the stream is not already open, the stream attempts to open 
for reading and writing. If that fails, the stream is opened for output only. 


5.2.4.15. lines 


+-Count--+ 
>>-lines (--+-------- %---)-------------------------------------- >< 
+-Normal-+ 


Returns the number of completed lines that available for input. If the stream has already been read with 
charInemphasis. this can include an initial partial line. For persistent streams the count starts at the 
current read position. In effect, lines reports whether a read action of charIn (see charIn) or lineIn (see 
lineIn) will succeed. (For an explanation of input and output, see Input and Output Streams.) 


For a Queue, lines returns the actual number of lines. 


Note: The chars method returns the number of characters in a persistent stream or the presence of 
data in a transient stream. The linesemphasis method determines the actual number of lines by 
scanning the stream starting at the current position and counting the lines. For large streams, this 
can be a time-consuming operation. Therefore, avoid the use of the LINES method in the condition of 
a loop reading a stream. It is recommended that you use the chars method. 


The ANSI Standard has extended this function to allow an option: "Count". If this option is used, lines 
returns the actual number of complete lines remaining in the stream, irrespective of how long this 
operation takes. 


The option "Normal" returns 1 if there is at least one complete line remaining in the file or O if no lines 
remain. 


The default is "Count". 


5.2.4.16. makeArray 


+- (LINES) -+ 
>>-шакеАггау--+--------- Sa a a ана аа–- >< 
+- (CHARS) -+ 


Returns a fixed array that contains the data of the stream in line or character format, starting from the 
current read position. The line format is the default. 


If you have used the charIn method, the first line can be a partial line. 
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5.2.4.17. open 


*-(BOTH-| Write Options |--%  *-SHARED----- * 
22 OPO Rats SSeS Se SSS asa Sasa + тата qglccccüBc-——- > 
*- (READ-------------------- + +-SHAREREAD--+ 


*-(WRITE-| Write Options |-+ +-SHAREWRITE-+ 


%----------------------------------- + 
V | 
»----4------------------------------- +-+--+---+---------------- >< 
*-NOBUFFER---------------------- * +-)-+ 
+-BINARY--+------------------- +-+ 


+-RECLENGTH--length-+ 


Write Options: 


V +-APPEND--+ | 
|----%--------- %-%---------------------------------------------- 
+-REPLACE-+ 


Opens the stream and returns READY:. If the method is unsuccessful, it returns an error message string in 
the same form that the description method uses. 


For most error conditions, the additional information is in the form of a numeric return code. This return 
code is the value of ERRNO, which is set whenever one of the file system primitives returns with a -1. 


By default, open opens the stream for both reading and writing data, for example: 'open BOTH'. To 
specify that the stream be only opened for input or output, specify READ or WRITE. 


The options for the open method are: 


READ 


Opens the stream for input only. 


WRITE 


Opens the stream for output only. 


BOTH 


Opens the stream for both input and output. (This is the default.) The stream maintains separate read 
and write pointers. 


APPEND 


Positions the write pointer at the end of the stream. (This is the default.) The write pointer cannot be 
moved anywhere within the extent of the file as it existed when the file was opened. 


REPLACE 


Sets the write pointer to the beginning of the stream and truncates the file. In other words, this 
option deletes all data that was in the stream when opened. 


200 ooRexx Reference Version 4.0.0 


Chapter 5. The Builtin Classes 


SHARED 


Enables another process to work with the stream in a shared mode. (This is the default.) This mode 
must be compatible with the shared mode (SHARED, SHAREREAD, or SHAREWRITE) used by 
the process that opened the stream. 


SHAREREAD 


Enables another process to read the stream in a shared mode. 


SHAREWRITE 


Enables another process to write the stream in a shared mode. 


NOBUFFER 


Turns off buffering of the stream. All data written to the stream is flushed immediately to the 
operating system for writing. This option can have a severe impact on output performance. Use it 
only when data integrity is a concern, or to force interleaved output to a stream to appear in the 
exact order in which it was written. 


BINARY 


Opens the stream in binary mode. This means that line-end characters are ignored; they are treated 
like any other byte of data. This is for processing binary record data using the line operations. 


Note: Specifying the BINARY option for a stream that does not exist but is opened for writing 
also requires the RECLENGTH option to be specified. Omitting the RECLENGTH option in this 
case raises an error condition. 


RECLENGTH length 


Allows the specification of an exact length for each line in a stream. This allows line operations on 
binary-mode streams to operate on individual fixed-length records. Without this option, line 
operations on binary-mode files operate on the entire file (for example, as if you specified the 
RECLENGTH option with a length equal to that of the file). The length must be 1 or greater. 


Examples: 
Stream name^open 


Stream name^open("write") 
Stream name^open("read") 


5.2.4.18. position 


+- = -+ +-СНАВ-+ 
»»-position(-4-----4-offset-*-READ--4-4------ %-)--------------- >< 

+- < -+ +-WRITE-+ +-LINE-+ 

+- + -+ 

+- - -+ 
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position is a synonym for seek. (See seek .) 


5.2.4.19. qualify 


a = sO aaa aaa >< 


Returns the stream’s fully qualified name. The stream need not be open. 


5.2.4.20. query 

>>-query (--+-DATETIME-------------------------- %--)------------ >< 
*-EXISTS---------------------------- * 
*-HANDLE---------------------------- * 
| +-CHAR-+ | 
+-+-SEEK-----+--+-READ--+------+--+-+ 
| +-POSITION-+ | +-LINE-+ | | 
| | *-CHAR-* | | 
| +-МАІТЕ--+------ +-+ | 
| | *-LINE-* | | 
| %-5Ү5------------- + | 
%-8І2Е------------------------------ + 
*-STREAMTYPE------------------------ * 
*-TIMESTAMP------------------------- * 


Used with these options, the query method returns specific information about a stream. Except for query 
HANDLE and query POSITION, the stream returns the query information even if the stream is not 
open. A null string is returned for nonexistent streams. 


DATETIME 
returns the date and time stamps of a persistent stream in US format. For example: 
stream name^query("datetime") 


A sample output might be: 


11-12-98 03:29:12 


EXISTS 
returns the full path specification of the stream, if it exists, or a null string. For example: 
stream_name~ query ("exists") 
A sample output might be: 


c:\data\file.txt 


HANDLE 
returns the handle associated with the open stream. For example: 
stream_name ~ query ("handle") 


A sample output might be: 
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POSITION 


returns the current read or write position for the stream, as qualified by the following options: 


READ 


returns the current read position. 
WRITE 
returns the current write position. 


Note: If the stream is open for both reading and writing, this returns the read position by default. 
Otherwise, this returns the specified position. 


CHAR 


returns the position in terms of characters. This is the default. 


LINE 


returns the position in terms of lines. For non-binary streams, this operation can take a long 
time to complete. This is because the language processor starts tracking the current line 
number if not already doing so, and, thus, might require a scan of the stream from the top to 
count the line-end characters. See Line versus Character Positioning for a detailed discussion 
of this issue. For example: 


stream name^query("position write") 
A sample output might be: 
247 

SYS 


returns the operating system stream position in terms of characters. 


SIZE 


returns the size, in bytes, of a persistent stream. For example: 


stream_name ~query ("size") 


A sample output might be: 
1305 


STREAMTYPE 


returns a string indicating whether the stream object is PERSISTENT, TRANSIENT, or UNKNOWN. 
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TIMESTAMP 


returns the date and time stamps of a persistent stream in an international format. This is the 
preferred method of getting the date and time because it provides the full 4-digit year. For example: 


stream_name ~query ("timestamp") 
A sample output might be: 


1998-11-12 03:29:12 


5.2.4.21. say 


QP Saya — -<<- SSS c m ----------------- >< 
+-(-+--------+-) -+ 
+-string-+ 


Returns 0 if successful in writing string to the output stream or 1 if an error occurs while writing the line. 


5.2.4.22. seek 


+- = -+ +-СНАВ-+ 

>>-seek (-+-----+-offset-+------- %-%------ %-)------------------- >< 
+- < -+ +-READ--+ +-LINE-+ 
+- + -+ +-WRITE-+ 
+- - -+ 


Sets the read or write position to a given number (offset) within a persistent stream. If the stream is open 
for both reading and writing and you do not specify READ or WRITE, both the read and write positions 
are set. 


Note: See Input and Output Streams for a discussion of read and write positions in a persistent 
stream. 


To use this method, you must first open the stream object (with the OPEN method described previously 
or implicitly with an input or output operation). One of the following characters can precede the offset 
number: 


Explicitly specifies the offset from the beginning of the stream. This is the default if you supply no 
prefix. For example, an offset of 1 means the beginning of the stream. 


Specifies offset from the end of the stream. 


Specifies offset forward from the current read or write position. 
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Specifies offset backward from the current read or write position. 


The seek method returns the new position in the stream if the read or write position is successfully 
located, or an appropriate error message. 


The following is a description of the options for seek: 


READ 


specifies that the read position be set. 


WRITE 


specifies that the write position be set. 


CHAR 


specifies that positioning be done in terms of characters. This is the default. 


LINE 


specifies that the positioning be done in terms of lines. For non-binary streams, this is potentially an 
operation that can take a long time to complete because, in most cases, the file must be scanned 
from the top to count the line-end characters. However, for binary streams with a specified record 
length, the new resulting line number is simply multiplied by the record length before character 
positioning. See Line versus Character Positioning for a detailed discussion of this issue. 


Note: If you do line positioning in a file open only for writing, you receive an error message. 


Examples: 


stream_name~seek("=2 read") 
stream_name~seek("+15 read") 
stream_name~seek("-7 write line") 
fromend = 125 
stream_name~seek("<"fromend read) 


5.2.4.23. state 


?22-вцав--------------<-+--- ++ Seas >< 


Returns a string indicating Ше current stream state. 


The returned strings are as follows: 
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ERROR 


The stream has been subject to an erroneous operation (possibly during input, output, or through the 
STREAM function). See Errors during Input and Output. You might be able to obtain additional 
information about the error with the description method or by calling the STREAM function with a 
request for the description. 


NOTREADY 


The stream is known to be in such a state that the usual input or output operations attempted upon 
would raise the NOTREADY condition. (See Errors during Input and Output.) For example, a 
simple input stream can have a defined length. An attempt to read that stream (with CHARIN or 
LINEIN, perhaps) beyond that limit can make the stream unavailable until the stream has been 
closed (for example, with LINEOUT(name)) and then reopened. 


READY 


The stream is known to be in such a state that the usual input or output operations might be 
attempted. This is the usual state for a stream, although it does not guarantee that any particular 
operation will succeed. 


UNKNOWN 


The state of the stream is unknown. This generally means that the stream is closed or has not yet 
been opened. 


5.2.4.24. string 


рва аа Ue. Ueeceu eee вариа аслаш >< 


Returns a string that indicates the name of ће object the stream represents i.e. the name of the file. 


5.2.4.25. supplier 


Blue) 0 ©) 9 aaa aaa a a a a >< 


Returns a StreamSupplier object for the stream containing the remaining stream lines and linenumber 
positions for the stream. 


5.2.4.26. uninit 


Be 0 aa aa aa a a a >< 


This method cleans up the object when it is garbage collected. It should not be invoked directly except 
via an uninit method of a subclass of the Stream class. 


If the Stream class is subclassed and the subclass provides an uninit method then that method must 
invoke the superclass uninit method. For example: 


::class CustomStream subclass Stream 
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::method uninit 

/* the subclass instance cleanup code should be placed here */ 
super^uninit -- this should be the last action in the method 
return 


5.3. The Collection Classes 


A collection is an object that contains a number of items, which can be any objects. Every item stored in 
a Rexx collection has an associated index that you can use to retrieve the item from the collection with 
the AT or [] methods. 


Each collection defines its own acceptable index types. Rexx provides the following collection classes: 


Array 


A sequenced collection of objects ordered by whole-number indexes. 


Bag 
A collection where the index and the item are the same object. Bag indexes can be any object and 
each index can appear more than once. 

CircularQueue 


The CircularQueue class allows for storing objects in a circular queue of a predefined size. Once the 
end of the queue has been reached, new item objects are inserted from the beginning, replacing 
earlier entries. The collected objects can be processed in FIFO (first in, first out) or in a stack-like 
LIFO (last in, first out) order. 

Directory 
A collection with character string indexes. Index comparisons are performed using the string == 
comparison method. 

List 
A sequenced collection that lets you add new items at any position in the sequence. A list generates 
and returns an index value for each item placed in the list. The returned index remains valid until the 
item is removed from the list. 


Properties 


A collection with character string indexes and values. Properties collections include support for 
saving and loading from disk files. 
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Queue 


A sequenced collection with the items ordered as a queue. You can remove items from the head of 
the queue and add items at either its tail or its head. Queues index the items with whole-number 
indexes, in the order in which the items would be removed. The current head of the queue has index 
1, the item after the head item has index 2, up to the number of items in the queue. 


Relation 


A collection with indexes that can be any object. A relation can contain duplicate indexes. 


Set 
A collection where the index and the item are the same object. Set indexes can be any object and 
each index is unique. 
Stem 
A collection with character string indexes constructed from one or more string segments. Index 
comparisons are performed using the string == comparison method. 
Table 
A collection with indexes that can be any object. A table contains no duplicate indexes. 
IdentityTable 


A collection with indexes that can be any object. The IdentityTable class determines index item 
matches by using an object identity comparison. With object identity matches, an index will only 
match the same object instance. An identity table contains no duplicate indexes. 


5.3.1. Organization of the Collection Classes 


The following shows the logical organization of the Collection Classes. This does NOT represent the 
order that methods are inherited but rather the organization of the classes. 


Collection 
MapCollection 
Directory 
Properties 
Relation 
Stem 
Table 
IdentityTable 
OrderedCollection 
Array 
List 
Queue 
CircularQueue 
SetCollection 
Bag 
Set 
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5.3.2. The Collection Class 


The Collection class is a MIXIN class that defines the basic set of methods implemented by all 
Collections. Many of the Collection class methods are abstract and must be implemented the inheriting 
subclasses. 


Figure 5-12. The Collection Class 





Collection 


alllndexes items 
allltems makeArray 
at, [] put, []- 
difference subset 
haslndex supplier 
hasltem union 
index xor 
intersection 








5.3.2.1. [] 


V | 
»»-[---index-4-]----------------------------------------------- >< 


Returns the item associated with the specified index or indexes. If the collection has no item associated 
with the specified index or indexes, this method returns the Nil object. This is an abstract method that 
must be implemented by a subclasses. 


5.3.2.2. []- 


V | 
»»-[---index--4-]-value----------------------------------------- >< 


Add an item to the collection at the specified index. This is an abstract method that must be implemented 
by a subclasses. 
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5.3.2.3. alllndexes 
>>-а111лдбехев----са- тата та лт-азатты саса >< 


Return ап array of all indexes used by this collection. This is an abstract method that must be 
implemented by a subclasses. 


5.3.2.4. allltems 


22 ad Tt ems SS Sse eS SS oe Sea SSS тат >< 


Return an array containing all items stored in the collection. This is an abstract method that must be 
implemented by a subclasses. 


5.3.2.5. at 


V | 
»»-at(---index-*-)--------------------------------------------- >< 


Returns the item associated with the specified index or indexes. If the collection has no item associated 
with the specified index or indexes, this method returns the Nil object. This is an abstract method that 
must be implemented by a subclasses. 


5.3.2.6. difference 


»»-difference(argument)---------------------------------------- >< 


Returns a new collection (of the same class as the receiver) containing only those items from the receiver 
whose indexes the argument collection does not contain. The argument can be any collection class 
object. The argument must also allow all of the index values in the receiver collection. 


5.3.2.7. hasindex 


V | 
»»-hasIndex(---index-4-)--------------------------------------- >< 


Returns 1 (true) if the array contains an item associated with the specified index or indexes. Returns 0 
(false) otherwise. 


5.3.2.8. hasltem 


»»-hasItem(item)----------------------------------------------- >< 
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Returns 1 (true) if the collection contains the specified item at any index location. Returns 0 (false) 
otherwise. 


5.3.2.9. index 


»»-index(item)------------------------------------------------- >< 


Return the index associated with item. If item occurs more than once in the collection, the returned index 
value is undetermined. This is an abstract method which must be implemented by a subclass of this class. 


5.3.2.10. intersection 


»»-intersection(argument)-------------------------------------- >< 


Returns a new collection (of the same class as the receiver) containing only those items from the receiver 
whose indexes are in both the receiver collection and the argument collection. The argument can be any 
collection class object. The argument must also allow all of the index values in the receiver collection. 


5.3.2.11. items 


Po Sib OMS aS SS ------#---+---+--#-+-++---++-++-----++<+ - + >< 


Returns the number of items in the collection. 


5.3.2.12. makeArray 


>2-шакетгтау------+-----------<--- aes >< 


Returns a single-index array with the same number of items as the receiver object. Any index with no 
associated item is omitted from the new array. Items in the new array will have the same order as the 
source array. 


5.3.2.13. put 


V | 
»»-put (item---,index-4-)--------------------------------------- >< 


Add an item to the collection at the specified index. This is an abstract method that must be implemented 
by a subclass if this class. 


5.3.2.14. subset 


>>-subset (argument)-------------------------------------------- >< 
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Returns 1 (true) if all indexes in the receiver collection are also contained in the argument collection; 
returns 0 (false) otherwise. The argument can be any collection class object. The argument must also 
allow all of the index values in the receiver collection. 


5.3.2.15. supplier 


>>-впррізег--------------- а-а SSSR SSR SS SRS SS SSS SS SSeS aS Sas >< 


Returns a Supplier object for the collection. The supplier allows you to enumerate through the index/item 
pairs for the collection. The supplier is created from a snapshot of the collection and is unaffected by 
subsequent changes to the collection’s contents. 


5.3.2.16. union 


»»-union(argument)--------------------------------------------- >< 


Returns a new collection of the same class as the receiver that contains all the items from the receiver 
collection and selected items from the argument collection. This method includes an item from argument 
in the new collection only if there is no item with the same associated index in the receiver collection and 
the method has not already included an item with the same index. The order in which this method selects 
items in argument is unspecified (the program should not rely on any order.). The argument can be any 
collection class object. The argument must also allow all of the index values in the receiver collection. 


5.3.2.17. xor 


»»-xor(argument)----------------------------------------------- >< 


Returns a new collection of the same class as the receiver that contains all items from the receiver 
collection and the argument collection; all indexes that appear in both collections are removed. The 
argument can be any collection class object. The argument must also allow all of the index values in the 
receiver collection. 


5.3.3. The MapCollection Class 


The MapCollection class is a MIXIN class that defines the basic set of methods implemented by all 
collections that use create a mapping from an index object to a value. 
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Figure 5-13. The MapCollection class 


Collection 
MapCollection 





This class is defined as a mixin class. 


5.3.3.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) — instanceMethod send 


=\===\== <> >< instanceMethods sendWith 
class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


Methods inherited from the Collection class. 


П hasIndex put 

ПЕ hasItem subset 
allIndexes index supplier 
allItems intersection union 

at items xor 


difference makeArray 


5.3.3.2. putAll 


»»-putAll(collection)------------------------------------------ >< 


Adds all items collection to the target directory. The collection argument can be any object that supports 
a supplier method. Items from collection are added using the index values returned by the supplier. The 
item indexes from the source collection must be strings. The items are added in the order provided by the 
supplier object. If duplicate indexes exist in collection, the last item provided by the supplier will 
overwrite previous items with the same index. 
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5.3.3.3. makeArray 


>>-шакейдгтау------- тата тт танат Seen SSS asses >< 


Returns а single-index array of the index values used by the receiver object. The index objects will not be 
ordered in any predictable order. 


5.3.4. The OrderedCollection Class 


The OrderedCollection class is a MIXIN class that defines the basic set of methods implemented by all 
collections that have an inherent index ordering, such as an array or a list. 


Figure 5-14. The OrderedCollection class 


Collections 





OrderedCollection 


append 
appendaAll 
difference 
intersection 
subset 
union 

xor 





This class is defined as a mixin class. 


5.3.4.1. append 
»»-append(item)------------------------------------------------ >< 


Append an item to the end of the collection ordering. This is an abstract method that must be 
implemented by a subclass if this class. 


5.3.4.2. аррепдА! 


»»-appendAll(collection)--------------------------------------- >< 
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Appends all items in collection to the end of the target collection. The collection may be any object that 
implements an allItems() method. 


5.3.4.3. difference 


»»-difference(argument)---------------------------------------- >< 


Returns a new collection (of the same class as the receiver) containing only those items from the receiver 
that are not also contained in the argument collection. The argument can be any collection class object. 


5.3.4.4. intersection 


»»-intersection(argument)-------------------------------------- >< 


Returns a new collection (of the same class as the receiver) containing only those items from the receiver 
that are in both the receiver collection and the argument collection. The argument can be any collection 
class object. 


5.3.4.5. subset 


>>-subset (argument)-------------------------------------------- >< 


Returns 1 (true) if all items in the receiver collection are also contained in the argument collection; 
returns 0 (false) otherwise. The argument can be any collection class object. 


5.3.4.6. union 


»»-union(argument)--------------------------------------------- >< 


Returns a new collection of the same class as the receiver that contains all the items from the receiver 
collection and selected items from the argument collection. This method includes an item from argument 
in the new collection only if there is no equivalent item in the receiver collection and the method has not 
already included. The order in which this method selects items in argument is unspecified (the program 
should not rely on any order.). The argument can be any collection class object. 


5.3.4.7. xor 


»»-xor(argument)----------------------------------------------- >< 


Returns a new collection of the same class as the receiver that contains all items from the receiver 
collection and the argument collection; all items that appear in both collections are removed. The 
argument can be any collection class object. 
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5.3.5. The SetCollection Class 


This is a tagging mixin class only and does not define any methods of its own. Collections that 
implement SetCollection are MapCollections that constrain the index and item to be be the same object. 


Figure 5-15. The SetCollection class 
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Collection 


SetCollection 


put, []- 





This class is defined as a mixin class. 


5.3.5.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) — instanceMethod send 


=\===\== <> >< instanceMethods sendWith 
class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


Methods inherited from the Collection class. 


П hasIndex put 

[= hasItem subset 
allIndexes index supplier 
allItems intersection union 

at items xor 


difference makeArray 


5.3.6. The Array Class 


An atray is a possibly sparse collection with indexes that are positive whole numbers. You can reference 
array items by using one or more indexes. The number of indexes is the same as the number of 
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dimensions of the array. This number is called the dimensionality of the array. 


Array items can be any valid Rexx object. If an object has not been assigned to an array index then that 
index is considered to contain the NIL object. 


Figure 5-16. The Array class and methods 
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new 

of 

alllndexes makeString 
allltems next 
append previous 

at, [] put, []= 
dimension remove 
empty removeltem 
first section 
haslndex size 
hasltem sort 

index sortWith 
isEmpty stableSort 
items stableSortWith 
last supplier 
makeArray toString 





Note: The Array class also has available class methods that its metaclass, the Class class, defines. 
It also inherits methods from the Ordered Collection class. 


Array objects are variable-sized. The dimensionality of an array is fixed, but the size of each dimension 
is variable. When you create an array, you can specify a hint about how many elements you expect to put 
into the array or the array's dimensionality. However, you do not need to specify a size or dimensionality 
of an array when you are creating it. You can use any whole-number indexes to reference items in an 
array. 


For any array method that takes an index, the index may be specified as either individual arguments or as 
an array of indexes. For example, the following are equivalent: 
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x = myarray[1,2,3] -- retrieves an item from a multi-dimension array 
index = .array^of(1,2,3) -- create an index list 
x = myarray [index] -- also retrieves from "1,2,3" 


Methods such as index() that return index items will return a single numeric value for single-dimension 
arrays and an array of indexes for multi-dimension arrays. 


5.3.6.1. Inherited Methods 
Methods inherited from the Object class. 


new (class method) — instanceMethod send 
=\= == \== <> >< instanceMethods sendWith 


class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


Methods inherited from the Collection class. 


П hasIndex put 

ПЕ hasItem subset 
allIndexes index supplier 
allItems intersection union 

at items xor 


difference makeArray 


Methods inherited from the OrderedCollection class. 


append intersection xor 
appendAll subset 
difference union 


5.3.6.2. new (Class Method) 


Returns a new empty array. If you specify any size arguments, the size is taken as a hint about how big 
each dimension should be. The Array classes uses this only to allocate the initial array object. For 
multiple dimension arrays, you can also specify how much space is to be allocated initially for each 
dimension of the array. 


Each size argument must a non-negative whole number. If it is 0, the corresponding dimension is initially 


empty. 
Examples: 
а = .array~new() -- create an new, empty array 
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5.3.6.3. of (Class Method) 


Returns a newly created single-index array containing the specified item objects. The first item has index 
1, the second has index 2, and so on. 


If you use the OF method and omit any argument items, the returned array does not include the indexes 
corresponding to those you omitted. 


Examples: 
a = .array~of("Fred", "Mike", "David") 
do name over a 


say name -- displays "Fred", "Mike", and "David" 
end 


5.3.6.4. [] 


V | 
»»-[---index-4-]----------------------------------------------- >< 


Returns the same value as the at() method. 


Note that the index argument may also be specified as an array of indexes. 


5.3.6.5. []- 


V | 
»»-[---index--4-]-value----------------------------------------- >< 


This method is the same as the put() method. 


Note that the index argument may also be specified as an array of indexes. 


5.3.6.6. alllndexes 


2o=alll Indexes sss SSS SSS SS SSS Sas SS SSS SRS SS SS SS SS eee >< 


Returns an array of all index positions in the array containing items. For multi-dimension arrays, each 
returned index will be an array of index values. 


Examples: 


a = .array~of("Fred", "Mike", "David") 
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do name over a~allIndexes 
say name -- displays "1", "2", and "3" 
end 


a^remove(2) -- remove second item 
do name over а а11Тпдехез 


say name -- displays "1" and "3" 
end 


5.3.6.7. allltems 


22-ай1Прешв------ a SS a Se aes >< 


Returns an array of all items contained in the array. 
Examples: 
a = .array~of("Fred", "Mike", "David") 
do name over a^allltems 


say name -- displays "Fred", "Mike", and "David" 
end 


a^remove(2) -- remove second item 
do name over a^allltems 


say name -- displays "Fred" and "David" 
end 


5.3.6.8. append 


»»-append(item)------------------------------------------------ >< 


Appends an item to the array after the last item (the item with the highest index). The return value is the 
index of newly added item. 


Examples: 


a = .array~of("Mike", "Rick") 
a^append("Fred") -- a = .array^of("Mike", "Rick", "Fred") 


V | 
»»-at(---index-*-)--------------------------------------------- >< 
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Returns the item associated with the specified index or indexes. If the array has no item associated with 
the specified index or indexes, this method returns the Nil object. 
Note that the index argument may also be specified as an array of indexes. 
Examples: 


a = .array~of("Mike", "Rick") 
say a^at(2) -- says: "Rick" 


5.3.6.10. dimension 


>>-аішепѕіоп-+----- qe SS SSS SS SSS Sse eee >< 
+-(n)-+ 


Returns the current size (upper bound) of dimension n (a positive whole number). If you omit n, this 
method returns the dimensionality (number of dimensions) of the array. If the number of dimensions has 
not been determined, 0 is returned. 


Examples: 
a = .array~of(,"Mike", "Rick") 
say a’ dimension -- says: 1 (number of dimensions in the array) 


say a^dimension(1) -- says: 3 (upper bound of dimension one) 


a = .array^new^^put("Mike",1,1)^^put("Rick",1,2) 


say a^dimension -- says: 2 (number of dimensions in the array) 
say a^dimension(1) -- says: 1 (upper bound of dimension one) 
say a^dimension(2) -- says: 2 (upper bound of dimension two) 
5.3.6.11. empty 
>?2>2-ешръу----------<- + -----<+-+- ---<-<+<+- <<< - << ---6 >< 


Removes all items from the array. 


Examples: 


a = .array~of("Mike", "Rick", "Fred", "Rick") 


а^ешрїу -- а = .array^new 
5.3.6.12. first 
POSES bse SSS SSS SSS SSS SS Sasa ec >< 


Returns the index of the first item in the array or the Nil object if the array is empty. For multi-dimention 
arrays, the index is returned as an array of index values. 


Examples: 
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a = .array~of("Mike", "Rick", "Fred", "Rick") 
say a^first -- says: 1 

a = .array~of(,"Mike", "Rick") 

say a^first -- says: 2 


5.3.6.13. Һаѕіпаех 


V | 
»»-hasIndex(---index-4-)--------------------------------------- >< 


Returns 1 (true) if the array contains an item associated with the specified index or indexes. Returns 0 
(false) otherwise. 
Note that the index argument may also be specified as an array of indexes. 


Examples: 


a = .array~of("Mike", "Rick", "Fred", "Rick") 
say a^hasIndex(2) -- says: 1 
say a^hasIndex(5) -- says: 0 


5.3.6.14. hasltem 


»»-hasItem(item)----------------------------------------------- >< 
Returns 1 (true) if the array contains the specified item at any index location. Returns 0 (false) otherwise. 
Item equality is determined by using the == method of item. 
Examples: 
a = .array~of("Mike", "Rick", "Fred", "Rick") 


say a^hasItem("Rick") -- says: 1 
say a^hasItem("Mark") -- says: 0 


5.3.6.15. index 


»»-index(item)------------------------------------------------- >< 


Returns the index of the specified item within the array. If the target item appears at more than one index, 
the first located index will be returned. For multi-dimension arrays, the index is returned as an array of 
index values. If the array does not contain the specified item, .nil is returned. Item equality is determined 
by using the == method of item. 


Examples: 


a = .array~of("Mike", "Rick", "Fred", "Rick") 
say a^index("Rick") -- says: 2 
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5.3.6.16. isEmpty 
>2- TSEmpbys=Sass ssa Sa тата та ата Sa Sea SSS Sass >< 


Returns 1 (true) if the array is empty. Returns 0 (false) otherwise. 


Examples: 
a = „аггау пен 
say a^isEmpty -- says: 1 
a [1] = "1" 
say a^isEmpty -- says: 0 


5.3.6.17. items 


>2-пьешв------- a Se ee Se SS Se Ss >< 


Returns the number of items in the collection. 


Examples: 
a = .array~of("Fred", , "Mike", , "David") 
say a^items -- says: 3 


5.3.6.18. last 


>> Last sass Sa ste a ae Sse тт я-я--еятяа 9 >< 


Returns the index of the last item in the array or the Nil object if the array is empty. For multi-dimension 
arrays, index is returned as an array of index items. 


Examples: 
a = .array~of("Fred", , "Mike", , "David") 
say a^last -- says: 5 


5.3.6.19. makeArray 


>2-шакейгтау---<-# acs SSeS ee SS rae еее таен еве >< 


Returns a single-index array with the same number of items as the receiver object. Any index with no 
associated item is omitted from the new array. Items in the new array will have the same order as the 
source array. Multi-dimension arrays arrays will be converted into a non-sparse single dimension array. 


Examples: 
a = .array~of("Fred", , "Mike", , "David") 
b = a^makeArray -- b = .array~of("Fred", "Mike", "David") 
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5.3.6.20. makeString 


+-,separator-+ 


+- (LINE) --+------------ +-+ 
>>-makeString (-+--------- %-------------- %-)-------------------- >< 
*- (CHAR) --* 


Returns a string that contains the data of an array. The elements of the array are treated either in line or 
character format, starting at the first element in the array. The line format is the default. If the line format 
is use, a separator string can be specified. The separator will be used between concatenated elements 
instead of the default line end separator. 


Examples: 


See toString for examples. 


5.3.6.21. next 


»»-next (index)------------------------------------------------- >< 


Returns the index of the item that follows the array item having index index or returns the Nil object if 
the item having that index is last in the array. For multi-dimention arrays, the same ordering used by the 
allItems method is used to determine the next position and the index is returned as an array of index 
values. 


Note that the index argument may also be specified as an array of indexes. 


Examples: 
a = .array^of("Fred", , "Mike", , "David") 
say a^next(3) -- says: 5 


5.3.6.22. previous 


>>-previous (index)--------------------------------------------- >< 


Returns the index of the item that precedes the array item having index index or the Nil object if the item 
having that index is first in the array. For multi-dimention arrays, the same ordering used by the allItems 
method is used to determine the previous position and the index is returned as an array of index values. 


Note that the index argument may also be specified as an array of indexes. 


Examples: 
a = .array~of("Fred", , "Mike", , "David") 
say a^previous(3) -- says: 1 


5.3.6.23. put 
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>>-put (item---,index-4-)--------------------------------------- >< 


Makes the object item a member item of the array and associates it with the specified index or indexes. 
This replaces any existing item associated with the specified index or indexes with the new item. If the 
index for a particular dimension is greater than the current size of that dimension, the array is expanded 
to the new dimension size. 


Note that the index argument may also be specified as an array of indexes. 


Examples: 


а = „аггау пен 

a^put("Fred", 1) -- a = .array^of("Fred") 
a^put("Mike", 2) -- a = .array^of("Fred", "Mike") 
a^put("Mike", 1) -- a = .array^of("Mike", "Mike") 


do name over a 
say name 
end 


/* Output would be: */ 


Mike 
Mike 


5.3.6.24. remove 


V | 
>>-гешоуе(---іпдех-%-)----------------------------------------- >< 


Returns and removes the member item with the specified index or indexes from the array. If there is no 
item with the specified index or indexes, the Nil object is returned and no item is removed. 


Note that the index argument may also be specified as an array of indexes. 


Examples: 


a = .array~of("Fred", "Mike", "Mike", "David") 


a^remove(2) -- removes "Mike" 


5.3.6.25. removeltem 


»»-removeltem(item)-------------------------------------------- >< 


Removes an item from the array. If the target item exists at more than one index, the first located item is 
removed. Item equality is determined by using the == method of item. The return value is the removed 
item. 


Examples: 


a = .array~of("Fred", "Mike", "Mike", "David") 


ooRexx Reference Version 4.0.0 225 


Chapter 5. The Builtin Classes 


a^removeltem("Mike") -- removes the item at index "2" 


5.3.6.26. section 


»»-section(start-4-------- %-)---------------------------------- >< 
+-,items-+ 


Returns a new array (of the same class as the receiver) containing selected items from the receiver array. 
The first item in the new array is the item corresponding to index start in the receiver array. Subsequent 
items in the new array correspond to those in the receiver array (in the same sequence). If you specify the 
whole number items, the new array contains only this number of items (or the number of subsequent 
items in the receiver array, if this is less than items). If you do not specify items, the new array contains 
all subsequent items of the receiver array. The receiver array remains unchanged. The section() method is 
valid only for single-index arrays. 


Note that the start argument, (the index argument,) may also be specified as an array of indexes. 


Examples: 
а = .array~of(1,2,3,4) -- Loads the array 
b = a^section(2) -- b = .array^of(2,3,4) 
c = a^section(2,2) -- c = .array^of(2,3) 
d = a^section(2,0) -- d = .array^new 


5.3.6.27. size 


>>-віге-------------------------------------------------------- >< 


Returns the number of items that can be placed in the array before it needs to be extended. This value is 
the same as the product of the sizes of the dimensions in the array. 


5.3.6.28. sort 


ames 1 © ia aa mm -<-<+< <<< -------< eet >< 


Sorts an array of Comparable items into ascending order using an unstable Quicksort algorithm. See 
Sorting Arrays for details. 


5.3.6.29. sortWith 


»»-sortWith(comparator)---------------------------------------- >< 


Sorts an array of items into ascending order using an unstable Quicksort algorithm. Ordering of elements 
is determined using the comparator argument. See Sorting Arrays for details. 
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5.3.6.30. stableSort 


>>-ввартеботв- sass SSRs sas SSS aaa SS SSS HSS SS SS SRS SSR SS SESS RRS ass >< 


Sorts an array of Comparable items into ascending order using a stable Mergesort algorithm. See Sorting 
Atrays for details. 


5.3.6.31. stableSortWith 


»»-stableSortWith(comparator)---------------------------------- >< 


Sorts an array of items into ascending order using a stable Mergesort algorithm. Ordering of elements is 
determined using the comparator argument. See Sorting Arrays for details. 


5.3.6.32. supplier 
POA SUPPLLOr = sss Ss SSSR SS HSS SR RRS RS SSS SRST SS Ss SSS ----- >< 


Returns a Supplier object for the collection. The supplier allows you to iterate over the index/item pairs 
for the collection. The supplier enumerates the array items in their sequenced order. For 
multi-dimensional arrays, the supplier index method will return the index values as an array of index 
numbers. 


Examples: 


a = .array~of("Fred", "Mike", "David") 
sup = a^supplier 

a^append("Joe") 

do while sup^available 


say sup~item -- displays "Fred", "Mike", and "David" 
sup^next 
end 
5.3.6.33. toString 
+- „верагатог-+ 
+- (LINE) --+------------ +-+ 
»»-toString(-4--------- %-------------- %-)---------------------- >< 
%-(СНАВ)--% 


Returns a string that contains the data of an array (one to n dimensional). The elements of the array are 
treated either in line or character format, starting at the first element in the array. The line format is the 
default. If the line format is use, a separator string can be specified. The separator will be used between 
concatenated elements instead of the default line end separator. 


Examples: 


a = .array~of(1,2,3,4) -- Loads the array 
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say а toString -- Produces: 1 
-- 2 
-- 3 
-- 4 
say a^toString("c") -- Produces: 1234 
say a^toString(, ", ") -- Produces: 1, 2, 3, 4 


5.3.6.34. Examples 
arrayil-.array^of(1,2,3,4) /ж Loads the array */ 


/* Alternative way to create and load an array */ 

array2-.array^new(4) /* Creates array2, containing 4 items */ 

do i-1 to 4 /* Loads the array */ 
аггау2[1]=і 

епа 


You can produce the elements loaded into an array, for example: 


do i=1 to 4 
say аггау! [1] 
end 


If you omit any argument values before arguments you supply, the corresponding indexes are skipped in 
the returned array: 


directions=.array~of("North","South", ,"West") 
do i=1 to 4 /* Produces: North ж/ 
say directions [і] /* South ж/ 
/ж The Nil object */ 
end /* West ж/ 


Неге is an example using the ~~: 
z=.array~of(1,2,3)~~put (4,4) 
do i = 1 to z^size 


say z[i] /* Produces: 12 3 4 */ 
end 


5.3.7. The Bag Class 


A bag is a non-sparse collection that restricts the elements to having an item that is the same as the index. 
Any object can be placed in a bag, and the same object can be placed in a bag several times. 
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Figure 5-17. The Bag class and methods 


+ MapCollection 


+ SetCollection 





of 

difference putAll 
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Note: The Bag class also has available class methods that its metaclass, the Class class, defines. It 
also inherits methods from the Set Collection class, although there are not currently any methods 
defined in that class. 


The Bag class is a subclass of the Relation class. In addition to its own methods, it inherits the methods 
of the Object class and the Relation class. 


5.3.7.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) “| instanceMethod send 


=\= == \== <> >< instanceMethods sendWith 
class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


Methods inherited from the Collection class. 
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П hasIndex put 

ШЕ: hasItem subset 
allIndexes index supplier 
allItems intersection union 

at items xor 


difference makeArray 


Methods inherited from the MapCollection class. 


putAll 


Methods inherited from the Relation class. 


new (class method) empty put 

allAt hasIndex | js 

allIndex hasItem remove 

allIndexes index removeltem 

allItems intersection subset 

at isEmpty supplier 
items union 

difference makeArray хог 


5.3.7.2. of (Class Method) 
V | 
»»-of(---item-4-)---------------------------------------------- >< 


Returns a newly created bag containing the specified item objects. 


5.3.7.3. |= 
>>- [index]-item------------------------------------------------ >< 


Adds an item to the Bag. This method is the same as the put() method. 


5.3.7.4. difference 
»»-difference(argument)---------------------------------------- >< 


Returns a new Bag containing only those items from the receiver that the the argument collection does 
not contain. The argument can be any collection class object. 


5.3.7.5. hasindex 
»»-hasIndex(index)--------------------------------------------- >< 


Returns 1 (true) if the collection contains any item associated with index index, or 0 (false). Index 
equality is determined by using the == method of index. 
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5.3.7.6. intersection 


»»-intersection(argument)-------------------------------------- >< 


Returns a new Bag containing only those items from the receiver that are in also in the argument 
collection. The argument can be any collection class object. 


5.3.7.7. put 


>>-put (item,index)--------------------------------------------- >< 


Makes the object item a member item of the bag and associates it with index index. If the relation already 
contains any items with index index, this method adds a new member item item with the same index, 
without removing any existing member items. 


5.3.7.8. putAll 


»»-putAll(collection)------------------------------------------ >< 


Adds all items collection to the target bag. The collection argument can be any object that supports a 
supplier method. Items from collection are added using the item values returned by the supplier. 


5.3.7.9. subset 


>>-subset (argument)-------------------------------------------- >< 


Returns 1 (true) if all indexes in the receiver collection are also contained in the argument collection; 
returns 0 (false) otherwise. The argument can be any collection class object. 


5.3.7.10. union 


»»-union(argument)--------------------------------------------- >< 


Returns a new Bag that contains all the items from the receiver collection and selected items from the 
argument collection. The order in which this method selects items in argument is unspecified. The 
argument can be any collection class object. 


5.3.7.11. xor 


»»-xor(argument)----------------------------------------------- >< 


Returns a new Bag that contains all items from the receiver collection and the argument collection; items 
that appear in both collections are removed. The argument can be any collection class object. 
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5.3.7.12. Examples 


/* Create a bag of fruit */ 
fruit = .bag^of("Apple", "Orange", "Apple", "Pear") 


say fruit~items /* How many pieces? (4) ж/ 
say fruit~items("Apple") /ж How many apples? (2) ж/ 
fruit^remove("Apple") /* Remove one of the apples. */ 


fruit^^put("Banana")^put("Orange") /* Add a couple. */ 
say fruit~items /* How many pieces? (5) */ 


5.3.8. The CircularQueue Class 


The CircularQueue class allows for storing objects in a circular queue of a predefined size. Once the end 
of the queue has been reached, new item objects are inserted from the beginning, replacing earlier 
entries. Any object can be placed in the queue and the same object can occupy more than one position in 
the queue. 


Figure 5-18. The CircularQueue class and methods 


* OrderedCollection 





CircularQueue 


of 

init resize 
makeArray size 
push string 
queue supplies 








Note: The CircularQueue class also has available class methods that its metaclass, the Class class, 
defines. 


The collected objects can be processed in FIFO (first in, first out) or in a stack-like LIFO (last in, first 
out) order. 
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5.3.8.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) — instanceMethod 
= \= == \== <> >< instanceMethods 
class isA 

copy isInstanceOf 
defaultName objectName 
hasMethod objectName= 
identityHash Request 

init Run 
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send 


sendWith 
setMethod 
Start 


startWith 
string 
unsetMethod 


Methods inherited from the Collection class. 


П hasIndex put 

ПЕ hasItem subset 
allIndexes index supplier 
allItems intersection union 

at items xor 


difference makeArray 


Methods inherited from the OrderedCollection class. 


append intersection xor 
appendAll subset 
difference union 


Methods inherited from the Queue class. 


new (class method) hasItem pull 

of (class method) index push 
allIndexes insert put 

allItems isEmpty | is 

append items queue 

at last remove 

[] makeArray removeltem 
empty next supplier 
first peek 

hasIndex previous 


5.3.8.2. of (Class Method) 


Returns a newly created circular queue containing the specified item objects. The first item has index 1, 
the second has index 2, and so on. The number of item objects determines the size of the circular queue. 


5.3.8.3. init 
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Performs initialization of the circular queue. 


5.3.8.4. makeArray 


>>-makeArray (-+--------- %-)------------------------------------ >< 
+--огдег--+ 
Returns a single-index array containing Ше items of the circular queue in the specified order. 


The following order can be used. (Only the capitalized letter is needed; all characters following it are 
ignored.) 


Fifo 


First-in, first-out order. This is the default. 


Lifo 


Last-in, first-out order (stacklike). 


5.3.8.5. push 


»»-push(item-4------------ S >< 
+--,option---+ 


Makes the object item a member item of the circular queue, inserting the item object in front of the first 
item in the queue. The pushed item object will be the new first item in the circular queue. 


If the circular queue is full, than the last item stored in the circular queue will be deleted, before the 
insertion takes place. In this case the deleted item will be returned, otherwise .nil. 


If option is specified, it may be "Normal" or "Unique". The default is "Normal". Only the first letter of 
the option capitalized letter is required; all characters following it are ignored. If option is Unique’, any 
matching item already in the queue will be removed before before item is added to the queue. removed 
before the operation is performed. This allows you to maintain a list like the recent files list of an editor. 


5.3.8.6. queue 


+--,Normal---+ 
»»-queue(item-4------------ %)---------------------------------- >< 
+--,Unique---+ 


Makes the object item a member item of the circular queue, inserting the item at the end of the circular 
queue. 


If the circular queue is full, than the first item will be deleted, before the insertion takes place. In this 
case the deleted item will be returned, otherwise .nil. 


If option is specified, it may be "Normal" or "Unique". The default is "Normal". Only the first letter of 
the option capitalized letter is required; all characters following it are ignored. If option is Unique’, any 
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matching item already in the queue will be removed before before item is added to the queue. removed 
before the operation is performed. This allows you to maintain a list like the recent files list of an editor. 


5.3.8.7. resize 


»»-resize(-newSize-4---------- Ж-)---------е--та----с--ттқ------ >< 
+--,order--+ 


Resizes the circular queue object to be able to contain newSize items. If the previous size was larger than 
newSize, any extra items are removed in the specified order. 


The following order can be used. (Only the capitalized letter is needed; all characters following it are 
ignored.) 


Fifo 
First-in, first-out. This keeps the most recently added items. This is the default action. 
Lifo 


Last-in, first-out (stacklike). This removes the most recently added items. 


Note:: Resizing with a value of 0 removes all items from the circular queue. 


5.3.8.8. size 


>>-а12е-------- + ae SSS ae ee SSS Se ae = >< 


Returns the maximum number of objects that can be stored in the circular queue. 


5.3.8.9. string 


fan" a ucc + +-,-Fifo--+ 
»»-string(-4----------- %--%--------- %-)------------------------ >< 
+-delimiter-+ +-,-order-+ 


Returns a string object that concatenates the string values of the collected item objects, using the 
delimiter string to delimit them, in the specified order. The default delimiter is a single comma. 


If the delimiter string argument is omitted the comma character (" , ") is used as the default delimiter 
string. 


The following order can be used. (Only the capitalized letter is needed; all characters following it are 
ignored.) 


Fifo 


First-in, first-out. This is the default 
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Lifo 


Last-in, first-out (stacklike) 


5.3.8.10. supplier 


»»-supplier(-4---------- %-)------------------------------------ >< 
+--огдег---+ 


Returns a Supplier object for the collection. The supplier allows you to iterate over Ше items that were in 
the queue at the time of the supplier’s creation. 


The supplier will iterate over the items in the specified order. (Only the capitalized letter is needed; all 
characters following it are ignored.) 


Fifo 


First-in, first-out, default 


Lifo 


Last-in, first-out (stacklike) 


5.3.8.11. Example 


-- create a circular buffer with five items 


u-.circularQueue^of("a", "b", "c", "А", "е") 

say "content: ["u"]," "content (LIFO): ["u^string("-»","[")"]" 

say 

u^resize(4, "ЕТЕО") -- resize fifo-style (keep newest) 

say "after resizing to 4 items in FIFO style (keeping the newest):" 
say "content: ["u"]," "content (LIFO): ["u^string("-»","L")"]" 

say 

u^resize(2, "LILO") -- resize lifo-style (keep oldest) 

say "after resizing to 2 items in LIFO style (keeping the oldest):" 
say "content: ["u"]," "content (LIFO): ["u^string("-»","L")"]" 

say 

u^resize(0) -- resize lifo-style (keep oldest) 

say "after resizing to 0 items, thereby deleting all items:" 

say "content: ["u"]," "content (LIFO): ["u~string("->","L")"]" 

say 

u^resize(2) -- resize lifo-style (keep oldest) 


say "after resizing to 2, size-"u^size "and items-"u^items 
u^^queue ('x') ^^queue (y) ^^queue Cz!) 

say "after queuing the three items 'x', !y', 'z':" 

say "content: ["u"]," "content (LIFO): ["u^string("-»","[")"]" 
say 
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u~~push('1')~~push('2') ~~push('3') 
say "after pushing the three items '1', '2', '3':" 


say "content: ["u"]," "content (LIFO): ["u~string("->","L")"]" 
say 
Output: 


content: [a,b,c,d,e], content (LIFO): [e->d->c->b->a] 


after resizing to 4 items in FIFO style (keeping the newest): 
content: [b,c,d,e], content (LIFO): [e->d->c->b] 


after resizing to 2 items in LIFO style (keeping the oldest): 
content: [b,c], content (LIFO): [c->b] 





after resizing to 0 items, thereby deleting all items: 
content: [], content (LIFO): П 


after resizing to 2, size-2 and items=0 
after queuing the three items 'x', 'y', ' 
content: [y,z], content (LIFO): [z->y] 


zi: 


after pushing the three items '1', '2', '3': 
content: [3,2], content (LIFO): [2->3] 


5.3.9. The Directory Class 


A Directory is a MapCollection using unique character string indexes. The items of the collection can be 
any valid Rexx object. 
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Figure 5-19. The Directory class and methods 


+ MapCollection 





new 

allindexes items 
allitems makeArray 
at, [] put, []- 
empty remove 
entry removeltem 
hasEntry setEntry 
haslndex setMethod 
hasltem supplier 
index unknown 
isEmpty unSetMethod 
items 








Note: The Directory class also has available class methods that metaclass, the Class class, defines. 
It also inherits methods from the Map Collection class, although there are not currently any methods 
defined in that class. 


In addition to the standard put() and at() methods defined for Collections, Directories provide access to 
objects using methods. For example: 


mydir - .directory^new 
mydir^name = "Mike" -- same as mydir^put("Mike", "NAME") 
say mydir^name -- same as say mydir[’NAME’] 


5.3.9.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) — instanceMethod send 
=\= ==\== <> >< instanceMethods sendWith 


class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
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identityHash Request unsetMethod 
init Run 


Methods inherited from the Collection class. 


П hasIndex put 

ПЕ hasItem subset 
allIndexes index supplier 
allItems intersection union 


at items XOr 
difference makeArray 


Methods inherited from the MapCollection class. 


putAll 


5.3.9.2. new (Class Method) 


Returns an empty Directory object. 


5.3.9.3. [] 


Returns the item corresponding to name. This method is the same as the at method. 


5.3.9.4. []- 


>>- [name] zitem------------------------------------------------- >< 


Adds or replaces the entry at index name. This method is the same as the put method. 


5.3.9.5. alllndexes 


so-alllndexés--------—--------—----ee meer eese irse >< 


Returns an array of all the directory indexes, including those of all the setMethod methods. 


5.3.9.6. allltems 
>2 аешв------+--------- ----------+--<--- >< 


Returns an array of all items contained in the directory, including those returned by all setMethod 
methods. 
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5.3.9.7. at 
»»-at(name)---------------------------------------------------- >< 


Returns the item associated with index name. If a method defined using setMethod is associated with 
index name, the result of running this method is returned. If the collection has no item or method 
associated with index name, the Nill object is returned. 


Example: 


say .environment^at("OBJECT") /ж Produces: "The Object class" */ 


5.3.9.8. empty 


Removes all items from the directory. Empty also removes all methods added using setMethod. 


5.3.9.9. entry 


>>-entry (name)------------------------------------------------- >< 


Returns the directory entry with name name (translated to uppercase). If there is no such entry, name 
returns the item for any method that setMethod supplied. If there is neither an entry nor a method for 
name the Nil object is returned. 


5.3.9.10. hasEntry 


>>-hasEntry (name)---------------------------------------------- >< 


Returns 1 (true) if the directory has an entry or a method for name name (translated to uppercase), or 0 
(false). 


5.3.9.11. hasindex 
»»-hasIndex(name)---------------------------------------------- >< 


Returns 1 (true) if the collection contains any item associated with index name, or 0 (false). 


5.3.9.12. hasltem 


»»-hasItem(item)---------------------------------------------- >< 


Returns 1 (true) if the collection contains the item at any index position or otherwise returns 0 (false). 
Item equality is determined by using the == method of item. 
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5.3.9.13. index 
»»-index(item)------------------------------------------------- >< 


Returns the index of the specified item within the directory. If the target item appears at more than one 
index, the first located index will be returned. If the directory does not contain the specified item, the Nil 
object is returned. Item equality is determined by using the == method of item. 


5.3.9.14. isEmpty 
>р-1вЕпру-------------------------<-----------<-+ >< 


Returns 1 (true) if Ше directory is empty. Returns 0 (false) otherwise. 


5.3.9.15. items 
22m OMNS SSSR SS SRS SSR SSSR SRR RRS RS SSS SSS SSS SS SSS SRS SRE SS SSS SS as >< 


Returns the number of items in the collection. 


5.3.9.16. makeArray 


22-makeArray----——————--——— e eMe E >< 


Returns a single-index array containing the index objects. The array indexes range from 1 to the number 
of items. The collection items appear in the array in an unspecified order. (The program should not rely 
on any order.) 


5.3.9.17. put 


>>-put (item,name)---------------------------------------------- >< 


Makes the object item a member item of the collection and associates it with index name. The new item 
replaces any existing item or method associated with index name. 


5.3.9.18. remove 


>>-гешоуе(паше)------------------------------------------------ >< 


Returns and removes the member item with index name from a collection. If a method is associated with 
setMethod for index name, the method is removed and running the method is returned. If there is no item 
or method with index name, the Nil object is returned. 
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5.3.9.19. removeltem 


»»-removeltem(item)-------------------------------------------- >< 


Removes an item from the directory. If the target item exists at more than one index, the first located item 
is removed. The return value is the removed item. Item equality is determined by using the == method of 
item. 


5.3.9.20. setEntry 


>>-setEntry (name-4-------- %-)---------------------------------- >< 
+-,entry-+ 


Sets the directory entry with name name (translated to uppercase) to the object entry, replacing any 
existing entry or method for name. If you omit entry, this method removes any entry or method with this 
name. 


5.3.9.21. setMethod 


>>-setMethod (паше-+--------- %-)-------------------------------- >< 
+-,method-+ 


Associates entry name name (translated to uppercase) with method method. Thus, the object returns the 
result of running method when you access this entry. This occurs when you specify name on the at, entry, 
or remove method. This method replaces any existing item or method for name. 


You can specify the name "UNKNOWN" as name. Doing so supplies a method that is run whenever an 
at() or entry() message specifies a name for which no item or method exists in the collection. This 
method's first argument is the specified directory index. This method has no effect on the action of any 
hasEntry, hasIndex, items, remove, or supplier message sent to the collection. 


The method can be a string containing a method source line instead of a method object. Alternatively, an 
array of strings containing individual method lines can be passed. In either case, an equivalent method 
object is created. 


If you omit method, setMethod() removes the entry with the specified name. 


5.3.9.22. supplier 


22-Büppidér---o-----------c е -------------- <<< >< 


Returns a Supplier object for Ше collection. The supplier allows you to iterate over the index/item pairs in 
the directory at the time the supplier was created. The supplier iterates the items in an unspecified order. 


5.3.9.23. unknown 


»»-unknown(messagename,messageargs)---------------------------- >< 
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Runs either the entry or setEntry method, depending on whether messagename ends with an equal sign. 
If messagename does not end with an equal sign, this method runs the entry() method, passing 
messagename as its argument. The messageargs argument is ignored. The entry() method is the return 
result. 


If messagename does end with an equal sign, this method runs the setEntry() method, passing the first 
part of messagename (up to, but not including, the final equal sign) as its first argument, and the first item 
in the array messageargs as its second argument. In this case, unknown() returns no result. 


5.3.9.24. unsetMethod 


>>-unsetMethod (name)------------------------------------------- >< 


Removes the association between entry name name (translated to uppercase) and a method. 


5.3.9.25. xor 


»»-xor(argument)----------------------------------------------- >< 


Returns a new Directory object containing all items from the receiver collection and the argument 
collection; all indexes that appear in both collections are removed. The argument can be any collection 
class object. The argument must also allow all of the index values in the receiver collection. 


5.3.9.26. Examples 


/кжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжж / 
/* A Phone Book Directory program ж/ 
/* This program demonstrates use of the directory class. ж/ 
/кжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжж / 


/* Define an UNKNOWN method that adds an abbreviation lookup feature. ж/ 
/* Directories do not have to have an UNKNOWN method. */ 
book = .directory^new^^setMethod("UNKNOWN", .methods["UNKNOWN"]) 


book["ANN" ] = "Ann B. ....... 555-6220" 

book["ann" - "Little annie . 555-1234" 

book["JEFF"] = "Jeff G. ...... 555-5115" 

book["MARK"] = "Mark C. ...... 555-5017" 

book["MIKE"] = "Mike H. ...... 555-6123" 

book^Rick = "Rick M. ...... 555-5110" /* Same as book["RICK"] = ... */ 
Do i over book /* Iterate over the collection */ 

Say book[i] 

end i 

Say "" /* Index lookup is case sensitive... ж/ 
Say Боокепъгу ("Міке") /* ENTRY method uppercases before lookup ж/ 
Say book["ANN"] /* Exact match ж/ 
Say book^ann /* Message sends uppercase before lookup ж/ 
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Say book["ann"] /* Exact match with lowercase index ж/ 
бау пи 

Say book["M"] /* Uses UNKNOWN method for lookup ж/ 
Say book["Z"] 

Exit 

/* Define an unknown method to handle indexes not found. */ 
/* Check for abbreviations or indicate listing not found */ 


::Method unknown 
Parse arg at_index 
value = "" 
Do i over self 
If abbrev(i, at_index) then do 


If value <> "" then value = value", " 
value = value || self^at(i) 
end 
end i 
If value = "" then value = "No listing found for" at_index 


Return value 


5.3.10. The List Class 


A list is a non-sparse sequenced collection similar to the Array Class to which you can add new items at 
any position in the sequence. The List creates a new index value whenever an item is added to the list and 
the associated index value remains valid for that item regardless of other additions or removals. Only 
indexes the list object generates are valid i.e. the list is never a sparse list and the list object will not 
modify indexes for items in the list. 
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Figure 5-20. The List class and methods 
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Note: The List class also has available class methods that its metaclass, metaclass, the Class class, 
defines. It also inherits methods from the Ordered Collection class, although there are not currently 
any methods defined in that class. 


5.3.10.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) — instanceMethod send 
=\===\== <> >< instanceMethods sendWith 


class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


Methods inherited from the Collection class. 


П hasIndex put 

Пе hasItem subset 
allIndexes index supplier 
allItems intersection union 

at items xor 


difference makeArray 


Methods inherited from the OrderedCollection class. 


append intersection xor 
appendAll subset 
difference union 


5.3.10.2. new (Class Method) 


Returns a new empty List object. 


5.3.10.3. of (Class Method) 
V | 
»»-of(---item-4-)---------------------------------------------- >< 


Returns a newly created list containing the specified item objects in the order specified. 
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5.3.10.4. [] 
»»- [index]----------------------------------------------------- >< 


Returns the item located at index. This is the same as the at method. 


5.3.10.5. []= 
>>- [index]-item------------------------------------------------ >< 


Replaces the item at index with item. This method is the same as the put method. 


5.3.10.6. alllndexes 


> t= Bel Eel 06 >>) am eese ieri >< 


Returns an array of all indexes contained in the list in the same order they are used in the list. 


5.3.10.7. allltems 


22-allltemB---—-—-——-———-—-——————— Sasa SS Sas sae aS SSR SaaS eii >< 


Returns an array of all items contained in the list in list iteration order. 


5.3.10.8. append 


»»-append(item)------------------------------------------------ >< 


Appends item to the end of the list, returning the index associated with item. 


5.3.10.9. at 


»»-at(index)--------------------------------------------------- >< 


Returns the item associated with index index. Returns the Nil object if the list has no item associated 
with index. 


5.3.10.10. empty 
22 CMD bY a re Re eR ы >< 


Removes all items from the list. 
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5.3.10.11. first 


Qe nL PS tote sss SaaS Sa Sea aa 5 аларның жі >< 


Returns the index of the first item in the list or the Nil object if the list is empty. 


5.3.10.12. firstltem 


Je Tits t bem soa a SS aa ee >< 


Returns the first item in the list or the Nil object if the list is empty. 


Example: 
musketeers=.list~of(Porthos,Athos,Aramis) /* Creates list MUSKETEERS */ 
item=musketeers~firstItem /* Gives first item in list ж/ 


/ж (Assigns "Porthos" to item) ж/ 


5.3.10.13. hasIndex 


»»-hasIndex(index)--------------------------------------------- >< 


Returns 1 (true) if the list contains any item associated with index index, or 0 (false). 


5.3.10.14. hasltem 


»»-hasItem(item)---------------------------------------------- >< 


Returns 1 (true) if the list contains the item at any index position or otherwise returns 0 (false). Пет 
equality is determined by using the == method of item. 


5.3.10.15. index 


»»-index(item)------------------------------------------------- >< 


Returns the index of the specified item within the list. If the target item appears at more than one index, 
the first located index will be returned. Returns the Nil object if the list does not contain the specified 
item. Item equality is determined by using the == method of item. 


5.3.10.16. insert 


>>-insert (item-+-------- %-)------------------------------------ >< 
+-,index-+ 
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Returns a list-supplied index for item item, which is added to the list. The inserted item follows an 
existing item with index index in the list ordering. If index is the Nil object, item becomes the first item in 
the list. If you omit index, the item becomes the last item in the list. 


Inserting an item in the list at position index will cause the items in the list after position index to have 
their relative positions shifted by the list object. The index values for any items in the list are not 
modified by the insertion. 


musketeers=.list~of(Porthos,Athos,Aramis) /* Creates list MUSKETEERS */ 
/* consisting of: Porthos */ 
/* Athos ж/ 
/ж Aramis ж/ 
index-musketeers^first /* Gives index of first item ж/ 
musketeers~ insert ("D'Artagnan",index) /ж Adds D'Artagnan after Porthos ж/ 
/* List is now: Porthos ж/ 
/ж D'Artagnan ж/ 
/ж Athos ж/ 
/ж Aramis ж/ 


/ж Alternately, you could use */ 
musketeers^insert("D'Artagnan",.nil) /* Adds D'Artagnan before Porthos */ 
/* List is now: D'Artagnan ж/ 


/* Porthos ж/ 
/ж Athos ж/ 
/ж Aramis ж/ 
/ж Alternately, you could use */ 
musketeers~ insert ("D'Artagnan") /* Adds D'Artagnan after Aramis ж/ 
/* List is now: Porthos ж/ 
/ж Athos ж/ 
/ж Aramis ж/ 
/ж D'Artagnan ж/ 
5.3.10.17. isEmpty 
22>. SEM bY ааа е ее тт ee pee mre >< 


Returns 1 (true) if the list is empty. Returns 0 (false) otherwise. 


5.3.10.18. items 


ee Doe See Sea SSS лена >< 


Returns the number of items in the list. 


5.3.10.19. last 


»»-last-------------------------------------------------------- >< 


Returns the index of the last item in the list or the Nil object if the list is empty. 
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5.3.10.20. lastltem 
>2-Тавъеш---- 9 Sea sea Sa san SSS SS Sa cornea erroe >< 


Returns the last item in the list or the Nil object if the list is empty. 


5.3.10.21. makeArray 


22-шакейггау----- явно тен a aes >< 


Returns а single-index array containing the list collection items. The array indexes range from 1 to Ше 
number of items. The order in which the collection items appear in the array is the same as their 
sequence in the list collection. 


5.3.10.22. next 
»»-next (index)------------------------------------------------- >< 


Returns the index of the item that follows the list item having index index. Returns the Nil object if index 
is the end of the list. 


5.3.10.23. previous 
>>-previous (index)--------------------------------------------- >< 


Returns the index of the item that precedes the list item having index index. Returns the Nil object if 
index is the beginning of the list. 


5.3.10.24. put 


>>-put (item,index)--------------------------------------------- >< 


Replaces any existing item associated with the specified index with the item. If index does not exist in the 
list, an error is raised. 


5.3.10.25. remove 


»»-remove(index)----------------------------------------------- >< 


Returns and removes from a collection the member item with index index. If no item has index index, 
this method returns the Nil object and removes no item. 


Removing an item from the list at position index will shift the relative position of items after position 
index. The index values assigned to those items will not change. 
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5.3.10.26. removeltem 


»»-removeltem(item)-------------------------------------------- >< 


Removes an item from the list. If the target item exists at more than one index, the first located item is 
removed. The return value is the removed item. Item equality is determined by using the == method of 
item. 


5.3.10.27. section 


»»-section(start-4-------- %-)---------------------------------- >< 
+-,items-+ 


Returns a new list (of the same class as the receiver) containing selected items from the receiver list. The 
first item in the new list is the item corresponding to index start in the receiver list. Subsequent items in 
the new list correspond to those in the receiver list (in the same sequence). If you specify the whole 
number items, the new list contains only this number of items (or the number of subsequent items in the 
receiver list, if this is less than items). If you do not specify items, the new list contains all subsequent 
items from the receiver list. The receiver list remains unchanged. 


5.3.10.28. supplier 


22^58Upplier-----—-—--—-——---———— e ecc SS SSS SRS aaa SS SSeS SSS = >< 


Returns a Supplier object for the list. The supplier allows you to iterate over the index/item pairs stored 
in the list at the time the supplier is created. The iteration is in the same order as the list sequence order. 


5.3.11. The Properties Class 


A properties object is a collection with unique indexes that are character strings representing names and 
items that are also restricted to character string values. Properties objects are useful for processing 
bundles of application option values. 
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Figure 5-21. The Properties class and methods 
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Note: The Properties class also has available class methods that its metaclass, the Class class, 
defines. 


5.3.11.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) — instanceMethod send 


= \= == \== <> >< instanceMethods sendWith 
class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


Methods inherited from the Collection class. 


П hasIndex put 

[= hasItem subset 
allIndexes index supplier 
allItems intersection union 


at items XOr 
difference makeArray 


Methods inherited from the MapCollection class. 
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putAll 


Methods inherited from the Directory class. 


allIndexes hasIndex [ j= 


allItems hasItem remove 

at index removeltem 
[] isEmpty setEntry 
empty items setMethod 
entry makeArray supplier 
hasEntry ри unsetMethod 


5.3.11.2. load (Class method) 


»»-load(source)------------------------------------------------ >< 


Loads a set of properties from source and returns them as a new Properties object. The load source can 
be either the string name of a file or a stream object. Properties are read from the source as individual 
lines using linein(). Blank lines and lines with a Rexx line comment ("--") as the first non-blank 
characters are ignored. Otherwise, the lines are assumed to be of the form "namezvalue" and are added 
to the receiver Properties value using name as the index for the value. 


5.3.11.3. new (Class method) 


Returns an empty Properties object. 


5.3.11.4. []= 


>>- [name] zitem------------------------------------------------- >< 


Adds item using the index index. This method is the same as the put() method. 


5.3.11.5. getLogical 


»»-getLogical(name-4---------- %-)------------------------------ >< 
+-,default-+ 


Returns the value of name as either .true or .false. The raw value of the name may be either the numeric 
values "0" or "1" or the string values "true" or "false". Any other value will raise a syntax error. If the 
property name does not exist and default has been specified, the default value will be returned. If default 
has not been specified, a syntax error is raised for missing values. 
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5.3.11.6. getProperty 


>>-getProperty (name-4---------- %-)----------------------------- >< 
+-,default-+ 


Returns the value of name. If property name does not exist and default has been specified, the default 
value will be returned. If default has not been specified, the Nil object is returned. 


5.3.11.7. getWhole 


»»-getWhole(name-4---------- %-)-------------------------------- >< 
+-,default-+ 


Returns the value of name, validated as being a Rexx whole number. If property name does not exist and 
default has been specified, the default value will be returned. If default has not been specified, a syntax 
error is raised for missing values. 


5.3.11.8. load 


»»-load(source)------------------------------------------------ >< 


Loads a set of properties into the receiving Properties object from source. The load source can be either 
the string name of a file or a stream object. Properties are read from the source as individual lines using 
linein(). Blank lines and lines with a Rexx line comment ("--") as the first non-blank characters are 
ignored. Otherwise, the lines are assumed to be of the form "name=value" and are added to the receiver 
Properties value using name as the index for the value. Properties loaded from source that have the same 
names as existing items will replace the current entries. 


5.3.11.9. put 


>>-put (item,name)---------------------------------------------- >< 


Makes the object item a member item of the collection and associates it with index name. The item value 
must be a character string. The new item replaces any existing item or method associated with index 
name. 


5.3.11.10. save 


»»-save(target)------------------------------------------------ >< 


Saves a set of properties into target. The save target can be either the string name of a file or a stream 
object. Properties are stored as individual lines using lineout(). The lines are written in the form 
"пате-уаше". A saved Properties file can be reloaded using the Properties load() method. 
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5.3.11.11. setLogical 
»»-setLogical(name,value)-------------------------------------- >< 


Sets a logical value in the property bundle. The value argument must be either the numbers "0" or "1", or 
the logical values .true or .false. The property value will be added with value converted in to the 
appropriate "true" or "false" string value. 


5.3.11.12. setProperty 
>>-setProperty (name,value)------------------------------------- >< 


Sets a named property in the property bundle. The value argument must be a character string value. 


5.3.11.13. setWhole 


»»-setWhole(name,value)---------------------------------------- >< 


Sets a whole number value in the property bundle. The value argument must be a valid Rexx whole 
number. 


5.3.12. The Queue Class 


A queue is a non-sparse sequenced collection with whole-number indexes. The indexes specify the 
position of an item relative to the head (first item) of the queue. Adding or removing an item changes the 
association of an index to its queue item. You can add items at either the tail or the head of the queue. 


ooRexx Reference Version 4.0.0 255 


Chapter 5. The Builtin Classes 


Figure 5-22. The Queue class and methods 


+ OrderedCollection 





new 

of 

allindexes last 
allltems makeArray 
append next 

at, [] peek 
empty previous 
first pull 
haslndex push 
hasltem put, Це 
index queue 
insert remove 
isEmpty removeltem 
items supplier 








Note: The Queue class also has available class methods that its metaclass, the Class class, defines. 
It also inherits methods from the Ordered Collection class. 


5.3.12.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) — instanceMethod send 


= \= == \== <> >< instanceMethods sendWith 
class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


Methods inherited from the Collection class. 
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П hasIndex put 

ШЕ: hasItem subset 
allIndexes index supplier 
allItems intersection union 

at items xor 


difference makeArray 


Methods inherited from the OrderedCollection class. 


append intersection xor 
appendAll subset 
difference union 


5.3.12.2. new (Class Method) 


Returns a new empty Queue object. 


5.3.12.3. of (Class Method) 


V | 
»»-of(---item-4-)---------------------------------------------- >< 


Returns a newly created queue containing the specified item objects in the order specified. 


5.3.12.4. [] 


>>- [index]----------------------------------------------------- >< 


Returns the item located at index index. This is the same as the at() method. 


5.3.12.5. []= 


>>- [index]-item------------------------------------------------ >< 


Replaces item at index with item. This method is the same as the put() method. 


5.3.12.6. alllndexes 


>2-а1пчехев----------------------------+-----+--<- >< 


Returns an array of all index values for Ше queue. For Ше Queue class, the indices are integers 1 - items. 
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5.3.12.7. allltems 


>>-а11Прешв---- 9 a Sea asa стат SS ---------------- >< 


Returns an array of all items contained in the queue, in queue order. 


5.3.12.8. append 
»»-append(item)------------------------------------------------ >< 


Appends item to the end of the queue, returning the index of the inserted item. 


5.3.12.9. at 


»»-at(index)--------------------------------------------------- >< 


Returns the item associated with index index. Returns the Nil object if the collection has no item 
associated with index. 


5.3.12.10. empty 
2? -ept s aS TSS SS aT SS SRST SE PS SSR STs SHR RRS SES >< 


Removes all items from the queue. 


5.3.12.11. first 


25 и а te SS ee >< 


Returns the index of the first item in the queue or the Nil object if the queue is empty. The index will 
always be | for non-empty queues. 


5.3.12.12. hasIndex 


»»-hasIndex(index)--------------------------------------------- >< 


Returns 1 (true) if the queue contains any item associated with index index, or 0 (false). 


5.3.12.13. hasltem 


»»-hasItem(item)---------------------------------------------- >< 


Returns 1 (true) if the queue contains the item at any index position or otherwise returns 0 (false). Item 
equality is determined by using the == method of item. 


258 ooRexx Reference Version 4.0.0 


Chapter 5. The Builtin Classes 


5.3.12.14. index 


»»-index(item)------------------------------------------------- >< 


Returns the index of the specified item within the queue. If the target item appears at more than one 
index, the first located index will be returned. Returns the Nil object if the queue does not contain the 
specified item. Item equality is determined by using the == method of item. 


5.3.12.15. insert 


>>-insert (item-+-------- %-)------------------------------------ >< 
+-,index-+ 


Returns a queue-supplied index for item, which is added to the queue. The inserted item follows any 
existing item with index index in the queue ordering. If index is the Nil object, item is inserted at the head 
of the queue. If you omit index, item becomes the last item in the queue. 


Inserting an item in the queue at position index will cause the items in the queue after position index to 
have their indexes modified by the queue object. 


musketeers=.queue~ of (Porthos,Athos,Aramis) /* Creates queue MUSKETEERS ж/ 
/* consisting of: Porthos ж/ 
/ж Athos ж/ 
/ж Aramis ж/ 
index-musketeers^first /* Gives index of first item */ 
musketeers^insert("D'Artagnan",index) /* Adds D'Artagnan after Porthos ж/ 
/* List is now: Porthos ж/ 
/ж D'Artagnan ж/ 
/ж Athos ж/ 
/ж Aramis ж/ 


/ж Alternately, you could use */ 
musketeers^insert("D'Artagnan",.nil) /* Adds D'Artagnan before Porthos */ 
/* List is now: D'Artagnan ж/ 


/ж Porthos ж/ 
/ж Athos ж/ 
/ж Aramis ж/ 
/ж Alternately, you could use */ 
musketeers~ insert ("D'Artagnan") /* Adds D'Artagnan after Aramis ж/ 
/* List is now: Porthos ж/ 
/ж Athos ж/ 
/ж Aramis ж/ 
/ж D'Artagnan ж/ 
5.3.12.16. isEmpty 
>> -1БЕшръу--< а ае --9-леротттаенне летен тата >< 


Returns 1 (true) if Ше queue is empty. Returns 0 (false) otherwise. 
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5.3.12.17. items 


22 ob ens SSS SoS See S тсе Тл лт та ааа 3 E >< 


Returns the number of items in the collection. 


5.3.12.18. last 


Returns the index of the last item in the queue or the Nil object if the queue is empty. 


5.3.12.19. makeArray 


>>-пакеАттаус-- sss So a наа >< 


Returns a single-index array containing the receiver queue items. The array indexes range from 1 to the 
number of items. The order in which the queue items appear in the array is the same as their queuing 
order, with the head of the queue as index 1. 


5.3.12.20. next 
»»-next (index)------------------------------------------------- >< 


Returns the index of the item that follows the queue item having index index or returns the Nil object if 
the item having that index is last in the queue. 


5.3.12.21. peek 


Returns the item at the head of the queue. Returns the Nil object if the queue is empty. The collection 
remains unchanged. 


5.3.12.22. previous 


>>-previous (index)--------------------------------------------- >< 


Returns the index of the item that precedes the queue item having index index or the Nil object if the item 
having that index is first in the queue. 


5.3.12.23. pull 
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Returns and removes the item at the head of the queue. Returns the Nil object if the queue is empty. 


5.3.12.24. push 


»»-push(item)-------------------------------------------------- >< 


Adds the object item to the head of the queue. 


5.3.12.25. put 


>>-put (item,index)--------------------------------------------- >< 


Replaces any existing item associated with the specified index with the new item. If the index does not 
exist in the queue, an error is raised. 


5.3.12.26. queue 


»»-queue(item)------------------------------------------------- >< 


Adds the object item to the tail of the queue. 


5.3.12.27. remove 


»»-remove(index)----------------------------------------------- >< 


Returns and removes from a collection the member item with index index. Returns the Nil object if no 
item has index index. 


5.3.12.28. removeltem 


»»-removeltem(item)-------------------------------------------- >< 


Removes an item from the queue. If the target item exists at more than one index, the first located item is 
removed. The return value is the removed item. Item equality is determined by using the == method of 
item. 


5.3.12.29. supplier 


>> -впррлег------------+<-<----<--- << +---- >< 


Returns a Supplierobject for Ше queue. The supplier allows you to iterate over the index/item pair 
contained in the queue at the time the supplier was created. The supplier iterates the items in their 
queuing order, with the head of the queue first. 
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5.3.13. The Relation Class 


A relation is a collection with indexes that can be any object. In a relation, each item is associated with a 
single index, but there can be more than one item with the same index (unlike a table, which can contain 
only one item for any index). 


Figure 5-23. The Relation class and methods 


+ MapCollection 
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allAt isEmpty 
allindex items 
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Note: The Relation class also has available class methods that its metaclass, the Class class, 
defines. It also inherits methods from the Map Collection class. 


5.3.13.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) — instanceMethod send 


=\= == \== <> >< instanceMethods sendWith 
class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
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init Run 


Methods inherited from the Collection class. 


П hasIndex put 

ПЕ hasItem subset 
allIndexes index supplier 
allItems intersection union 

at items xor 


difference makeArray 


Methods inherited from the MapCollection class. 


putAll 


5.3.13.2. new (Class Method) 


Returns an empty Relation object. 


5.3.13.3. [] 


»»- [index]----------------------------------------------------- >< 


Returns an item associated with index. Thie is the same as the at() method. 


5.3.13.4. []- 


>>- [index]-item------------------------------------------------ >< 


Adds item to the relation associated with index index. This is the same as the put() method. 


5.3.13.5. allAt 


>>-al LAt (index)------------------------------------------------ >< 


Returns a single-index array containing all the items associated with index index. Items in the array 
appear in an unspecified order. Index equality is determined by using the == method of index. 


5.3.13.6. alllndex 


»»-allIndex(item)---------------------------------------------- >< 


Returns a single-index array containing all indexes for item item, in an unspecified order. Item equality is 
determined by using the == method of item. 
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5.3.13.7. alllndexes 
>>-а1Ппдехев-----<------- ++ << SSS esas >< 


Returns an array of all indexes contained in Ше Relation. The returned array will have one index for 
every item stored in the relation, including duplicates. Duplicate indexes can be removed easily by 
converted the array to a set. 


-- retrieve the unique index items 


indexes = .set~new~union(relation~allindexes) 
5.3.13.8. allltems 
22-а Lt CMB ee -#----+-#-----+-- EE >< 


Returns an array of all items contained in the relation. 


5.3.13.9. at 


»»-at(index)--------------------------------------------------- >< 


Returns the item associated with index index. If the relation contains more than one item associated with 
index index, the item returned is unspecified. (The program should not rely on any particular item being 
returned.) Returns the Nil object if the relation has no item associated with index index. Index equality is 
determined by using the == method of index. 


5.3.13.10. difference 


»»-difference(argument)---------------------------------------- >< 


Returns a new Relation containing only those items that the argument collection does not contain (with 
the same associated index). The argument can be any collection class object. 


5.3.13.11. empty 


eS 3.0), aa a a a a aa aaa a a >< 


Removes all items from the relation. 


5.3.13.12. hasIndex 


»»-hasIndex(index)--------------------------------------------- >< 


Returns 1 (true) if the collection contains any item associated with index index, or 0 (false). Index 
equality is determined by using the == method of index. 
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5.3.13.13. hasltem 


>>-hasItem(item-+-------- +-)------9-т 9959555 -а E >< 
+-,index-+ 


Returns 1 (true) if the relation contains the member item item, 0 (false). If index is specified, hasIndex() 
will only return true if the relation contains the pairing of item associated with index index. Item and 
index equality is determined by using the == method. 


5.3.13.14. index 


»»-index(item)------------------------------------------------- >< 


Returns the index for item item. If there is more than one index associated with item item, the one 
returned is not defined. Item equality is determined by using the == method of item. 


5.3.13.15. intersection 


»»-intersection(argument)-------------------------------------- >< 


Returns a new collection (of the same class as the receiver) containing only those items that are in both 
the receiver collection and the argument collection with the same associated index. The argument can be 
any collection class object. 


5.3.13.16. isEmpty 


>2-1вЕшръу------+----+---+#----+-+<+<++-++-+-+--++++<+- << ---+ + + <- >< 


Returns 1 (true) if the relation is empty. Returns 0 (false) otherwise. 


5.3.13.17. items 


>>-items-+--------- a a a a + -<-- >< 
*- (index) -+ 


Returns the number of relation items with index index. If you specify no index, this method returns the 
total number of items associated with all indexes in the relation. Index equality is determined by using 
the == method of index. 


5.3.13.18. makeArray 


>2-шакейтгтау----------5-------------+-- ee >< 


Returns a single-index array containing the index objects. The collection items appear in the array in an 
unspecified order. 
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5.3.13.19. put 
>>-put (item,index)--------------------------------------------- >< 


Makes the object item a member item of the relation and associates it with index index. If the relation 
already contains any items with index index, this method adds a new member item item with the same 
index, without removing any existing member items. 


5.3.13.20. remove 


»»-remove(index)----------------------------------------------- >< 


Returns and removes from a relation the member item with index index. If the relation contains more 
than one item associated with index index, the item returned and removed is unspecified. Returns the Nil 
object if no item has index index. Index equality is determined by using the == method of index. 


5.3.13.21. removeltem 


»»-removeltem(item,index)-------------------------------------- >< 


Returns and removes from a relation the member item item (associated with index index). Returns the Nil 
object if value is not a member item associated with index index. If item is the only member with index) 
then the index) is also removed from the Relation. 


5.3.13.22. subset 


>>-subset (argument)-------------------------------------------- >< 


Returns 1 (true) if all items in the receiver Relation are also contained in the argument collection with the 
same associated index; returns 0 (false) otherwise. The argument can be any collection class object. 


5.3.13.23. supplier 


22-supplier--t--------- lxxx c MEC ECCL CC EN >< 
*- (index) -+ 


Returns a The Supplier Class object for the relation. The supplier allows you to iterate over all 
index/item pairs in the relation at the time the supplier was created. The supplier enumerates the items in 
an unspecified order. If you specify index, the supplier contains all of the items with the specified index. 


5.3.13.24. union 


»»-union(argument)--------------------------------------------- >< 


Returns a new collection containing all items from the receiver collection and the argument collection. 
The argument can be any collection class object. 
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5.3.13.25. xor 
»»-xor(argument)----------------------------------------------- >< 


Returns a new collection of the same class as the receiver that contains all items from the receiver 
collection and the argument collection. All index-item pairs that appear in both collections are removed. 
The argument can be any collection class object. 


5.3.13.26. Examples 


/* Use a relation to express parent-child relationships */ 


family = .relation new 

family["Henry"] = "Peter" /* Peter is Henry's child  */ 
family["Peter"] = "Bridget" /* Bridget is Peter's child */ 
family["Henry"] = "Jane" /* Jane is Henry's child ж/ 


/* Show all children of Henry recorded in the family relation */ 
henrys_kids = family~allAt ("Henry") 
Say "Here are all the listed children of Henry:" 
Do kid Over henrys_kids 
Say " "kid 
End 


/* Show all parents of Bridget recorded in the family relation */ 
bridgets_parents = family~allIndex("Bridget") 
Say "Here are all the listed parents of Bridget:" 
Do parent Over bridgets_parents 
Say " "parent 
End 


/* Display all the grandparent relationships we know about. */ 


checked_for_grandkids = .set^new /* Records those we have checked */ 
Do grandparent Over family /* Iterate for each index in family ж/ 
If checked, for grandkids^hasIndex(grandparent) 

Then Iterate /* Already checked this one ж/ 
kids = family~allat (grandparent) /* Current grandparent's children ж/ 
Do kid Over kids /* Iterate for each item in kids ж/ 

grandkids = family~allAt (kid) /* Current kid's children */ 

Do grandkid Over grandkids /* Iterate for each item in grandkids */ 

Say grandparent "has a grandchild named" grandkid"." 

End 
End 
checked, for grandkids^put(grandparent) /* Add to already-checked set ж/ 


End 
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5.3.14. The Set Class 


A Set is a collection containing member items where the index is the same as the item (similar to a Bag 
collection). Any object can be placed in a set. There can be only one occurrence of any object in a set 
(unlike a Bag collection). Item equality is determined by using the == method. 


Figure 5-24. The Set class and methods 
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Note: The Set class also has available class methods that its metaclass, the Class class, defines. 


The Set class is a subclass of the Table class. In addition to its own methods, it inherits the methods of 
the Object class (see The Object Class) and the Table class. It also inherits methods from the Set 
Collection class. 


5.3.14.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) — instanceMethod send 


= \= == \== <> >< instanceMethods sendWith 
class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
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hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


Methods inherited from the Collection class. 


П hasIndex put 

= һаѕ Кет subset 
allIndexes index supplier 
allItems intersection union 

at items xor 


difference makeArray 


Methods inherited from the MapCollection class. 


putAll 


Methods inherited from the Table class. 


new (class method) hasIndex put 


allIndexes hasItem |j 
allItems index remove 

at isEmpty removeltem 
[] items supplier 
empty makeArray 


5.3.14.2. of (Class Method) 
V | 
»»-of(---item-4-)---------------------------------------------- >< 


Returns a newly created set containing the specified item objects. 


5.3.14.3. [|= 


>>- [index]-item------------------------------------------------ >< 


Add an item to the Set. This method is the same as the put() method. 


5.3.14.4. intersection 


»»-intersection(argument)-------------------------------------- >< 


Returns a new collection (of the same class as the receiver) containing only those items from the receiver 
whose indexes are in both the receiver collection and the argument collection. The argument can be any 
collection class object. The argument must also allow all of the index values in the receiver collection. 
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5.3.14.5. put 


>>-put (item-4-------- %-)----------------------------------------- >< 
+-,index-+ 


Adds item to the Set. If there is an equivalent item in the Set, the exiting item will be replaced by the new 
instance. Item equality is determined by using the == method of item. If index is specified, it must be the 
same as item. 


5.3.14.6. putAll 


»»-putAll(collection)------------------------------------------ >< 


Adds all items collection to the target set. The collection argument can be any object that supports a 
supplier method. Items from collection are added using the item values returned by the supplier. If 
duplicate items exist in collection, the last item provided by the supplier will overwrite previous items 
with the same index. 


5.3.14.7. subset 


>>-subset (argument)-------------------------------------------- >< 


Returns 1 (true) if all items in the receiver collection are also contained in the argument collection; 
returns 0 (false) otherwise. The argument can be any collection class object. The argument must also 
allow all of the index values in the receiver collection. 


5.3.14.8. union 


»»-union(argument)--------------------------------------------- >< 


Returns a new Set contains all the items from the receiver collection and selected items from the 
argument collection. This method includes an item from argument in the new collection only if there is 
no item already in the in the receiver collection and the method has not already included a matching 
item. The order in which this method selects items in argument is unspecified. The argument can be any 
collection class object. The argument must also allow all of the index values in the receiver collection. 


5.3.14.9. xor 


»»-xor(argument)----------------------------------------------- >< 


Returns a new Set that contains all items from the receiver collection and the argument collection; all 
items that appear in both collections are removed. The argument can be any collection class object. The 
argument must also allow all of the index values in the receiver collection. 
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5.3.15. The Stem Class 


A stem object is a collection with unique indexes that are character strings. 


Figure 5-25. The Stem class and methods 
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Note: The Stem class also has available class methods that its metaclass, the Class class, defines. 
It also inherits methods from the Map Collection class. 


Stems are automatically created whenever a Rexx stem variable or Rexx compound variable is used. For 
example: 


а.1 + 2 


creates а new stem collection with Ше name A. and assigns it to Ше Rexx variable A.; it also assigns Ше 
value 2 to entry 1 in the collection. 


The value of an uninitialized stem index is the stem object NAME concatenated with the derived stem 
index. For example 


say a.[1,2] -- implicitly creates stem object with name "A." 
-- displays "A.1.2" 


а = .stem^new("B.") 
say a[1,2] -- displays "B.1.2" 
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In addition to the items explicitly assigned to the collection indexes, a value may be assigned to all 
possible stem indexes. The []= method (with no index argument) will assign the target value to all 
possible stem indexes. Following assignment, a reference to any index will return the new value until 
another value is assigned or the index is dropped. 


The П method (with no index specified) will retrieve any globally assigned value. By default, this 
returns the stem NAME value. 


In addition to the methods defined in the following, the Stem class removes the methods =, ==, \=, \==, 
<>, and >< using the DEFINE method. 


5.3.15.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) instanceMethod send 
=\= == \== <> >< instanceMethods sendWith 


class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


Methods inherited from the Collection class. 


П hasIndex put 

ПЕ hasItem subset 
allIndexes index supplier 
allItems intersection union 

at items xor 


difference makeArray 


Methods inherited from the MapCollection class. 


putAll 


5.3.15.2. new (Class Method) 


»»-new-t-------- ll rM C ECC m >< 
+- (name) -+ 


Returns a new stem object. If you specify a string name, this value is used to create the derived name of 
compound variables. The default stem name is a null string (""). 


5.3.15.3. [] 


+-index-+ 
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Returns the item associated with the specified indexes. Each index is an expression; use commas to 
separate the expressions. The Stem object concatenates the index string values, separating them with a 
period (.), to create a derived index. A null string ("") is used for any omitted expressions. The resulting 
string is the index of the target stem item. If the stem has no item associated with the specified final 
index, the stem default value is returned. If a default value has not been set, the stem name concatenated 
with the final index string is returned. 


If you do not specify index, the stem default value is returned. If no default value has been assigned, the 
stem name is returned. 


Note: You cannot use the [] method in a DROP or PROCEDURE instruction. 


5.3.15.4. []- 


+-index-+ 


Makes the value a member item of the stem collection and associates it with the specified index. The 


"on 


final index is derived by concatenation each of the index arguments together with a "." separator. If you 
specify no index arguments, a new default stem value is assigned. Assigning a new default value will 
re-initialize the stem and remove all existing assigned indexes. 


5.3.15.5. alllndexes 


2»-aliIndexés----2------—2---——----ero San Se Se eene Sass >< 


Returns an array of all the stem tail names used in the stem. 


5.3.15.6. allltems 


22 а CMs SS eS SP Ss >< 


Returns an array of all items contained in the stem. 


5.3.15.7. at 


>>-at (tail) ---------------------------------------------------- >< 


Returns the item associated with the specified tail. The Nil object is returned if the stem has no item 
associated with the specified tail. 
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5.3.15.8. empty 
22 SOP CY ee a ea Re ease >< 


Removes all items from the stem. 


5.3.15.9. hasIndex 


»»-hasIndex(tail)---------------------------------------------- >< 


Returns 1 (true) if the collection contains any item associated with a stem tail tail, or 0 (false). 


5.3.15.10. hasltem 


»»-hasItem(value)---------------------------------------------- >< 


Returns 1 (true) if the collection contains the value at any tail position or otherwise returns 0 (false). Item 
equality is determined by using the == method of item. 


5.3.15.11. index 


»»-index(item)------------------------------------------------- >< 


Returns the index of the specified item within the stem. Returns the Nil object if the stem does not 
contain the specified item. Item equality is determined by using the == method of item. 


5.3.15.12. isEmpty 
>2-1вЕпръу------#--------+#---#+---+-+-#----++---+-++#++--+-+<+<++ + +- + >< 


Returns 1 (true) if the stem is empty. Returns 0 (false) otherwise. 


5.3.15.13. items 


Returns the number of items in the collection. 


5.3.15.14. makeArray 


22z:makéArray-----ze------oc6soccocooenoeneoeconocennonco aec nep >< 


Returns an array of all stem indexes that currently have an associated value. The items appear in the 
array in an unspecified order. 
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5.3.15.15. put 
>>-put (item,tail)---------------------------------------------- >< 


Replaces any existing item associated with the specified tail with the new item item. 


5.3.15.16. remove 
»»-remove(tail)------------------------------------------------ >< 


Returns and removes from the stem the member item with index tail. Returns the Nil object if no item 
has index tail. 


5.3.15.17. removeltem 
»»-removeltem(item)-------------------------------------------- >< 


Removes an item from the stem. If the target item exists at more than one tail, the first located item is 
removed. Item equality is determined by using the == method of item. The return value is the removed 
item. 


5.3.15.18. request 


»»-request(classid)-------------------------------------------- >< 


This method requests conversion to a specific class. All conversion requests except Array are forwarded 
to the stem’s current stem default value. Returns the result of the Stem class makeArray method, if the 
requested class is Array. For all other classes, request forwards the message to the stem object’s default 
value. 


5.3.15.19. supplier 


PPSSUPP LOT ass asst SSS SS SSSR a SS SS SSS Sr SSS SSR SSS SaaS eee >< 


Returns a Supplier object for the stem. The supplier allows you to iterate though the index/item pairs 
contained in the Stem object at the time the supplier was created. The supplier iterams the items in an 
unspecified order. 


5.3.15.20. toDirectory 


> 0) Bs 1607 faa cn нынын >< 


Returns a Directory object for the stem. The directory will contain a name/value pair for each stem index 
with a directly assigned value. 
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5.3.15.21. unknown 
>>-unknown- (messagename ,messageargs ) --------------------------- >< 


Reissues or forwards all unknown messages to the stem’s current default value. For additional 
information, see Defining an unknown Method. 


5.3.16. The Table Class 


A table is a collection with indexes that can be any object. In a table, each item is associated with a single 
index, and there can be only one item for each index (unlike a relation, which can contain more than one 
item with the same index). Index equality is determined by using the == method. 


Figure 5-26. The Table class and methods 


+ MapCollection 





new 
alllndexes isEmpty 
allltems items 

at, [] makeArray 
empty put, []- 
hasindex remove 
hasltem removeltem 
index supplier 








Note: The Table class also has available class methods that its metaclass, the Class class, defines. 
It also inherits methods from the Map Collection class. 


5.3.16.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) — instanceMethod send 
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= === 54 instanceMethods send With 


class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


Methods inherited from the Collection class. 


П hasIndex put 

[= hasItem subset 
allIndexes index supplier 
allItems intersection union 


at items XOr 
difference  makeArray 


Methods inherited from the MapCollection class. 


putAll 


5.3.16.2. new (Class Method) 


Returns an empty Table object. 


5.3.16.3. [] 


»»- [index]----------------------------------------------------- >< 


Returns the item associated with index. This is the same as the at() method. 


5.3.16.4. []- 


>>- [index]-item------------------------------------------------ >< 


Adds item to the table at index index. This method is the same as the put() method. 


5.3.16.5. alllndexes 


>2-а Ппдехев----я-----ненняяня-няня ня >< 


Returns an array of all indexes contained in Ше table. 


5.3.16.6. allltems 


22а El = 11> cna SL >< 
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Returns an array of all items contained in the table. 


5.3.16.7. at 


»»-at(index)--------------------------------------------------- >< 


Returns the item associated with index index. Returns the Nil object if the collection has no item 
associated with index. 


5.3.16.8. empty 


22 CUD GY oe eS 8200 >< 


Removes all items from the table. 


5.3.16.9. Һаѕіпаех 


»»-hasIndex(index)--------------------------------------------- >< 


Returns 1 (true) if the collection contains any item associated with index index, or 0 (false). 


5.3.16.10. hasltem 


»»-hasItem(value)---------------------------------------------- >< 


Returns 1 (true) if the collection contains the value at any index position or otherwise returns 0 (false). 
Item equality is determined by using the == method of item. 


5.3.16.11. index 


»»-index(item)------------------------------------------------- >< 


Returns the index of the specified item within the table. If the target item appears at more than one index, 
the first located index will be returned. Returns the Nil object if the table does not contain the specified 
item. Item equality is determined by using the == method of item. 


5.3.16.12. isEmpty 


Ba) OS 9) aa a a aa ea a ac >< 


Returns 1 (true) if the table is empty. Returns 0 (false) otherwise. 
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5.3.16.13. items 
>2-твешв--<---#нн<н <<< RR SSR RRR RS SSS SRST тесен 9 >< 


Returns the number of items in the collection. 


5.3.16.14. makeArray 


>>-шакейггау------------- -+--<-<+---------- >< 


Returns a single-index array containing the index objects. The array indexes range from 1 to Ше number 
of items. The collection items appear in the array in an unspecified order. 


5.3.16.15. put 
>>-put (item,index)--------------------------------------------- >< 


Makes the object item a member item of the collection and associates it with index index. The new item 
replaces any existing items associated with index index. 


5.3.16.16. remove 


»»-remove(index)----------------------------------------------- >< 


Returns and removes the table item with index index. Returns the Nil object if no item has index index. 


5.3.16.17. removeltem 


»»-removeltem(item)-------------------------------------------- >< 


Removes an item from the table. If the target item exists at more than one index, the first located item is 
removed. The return value is the removed item. Item equality is determined by using the == method of 
item. 


5.3.16.18. supplier 


>2-виррпег-----------------------------<- >< 


Returns a Supplier object for Ше collection. The supplier allows you iterate over the index/item pairs 
contained in the table at the time the supplier was created. The supplier iterates over the items in an 
unspecified order. 
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5.3.17. The IdentityTable Class 


An identity table is a collection with indexes that can be any object. In an identity table, each item is 
associated with a single index, and there can be only one item for each index. Index and item matches in 
an identity table are made using an object identity comparison. That is, an index will only match if the 
same instance is used in the collection. 


Figure 5-27. The IdentityTable class and methods 


IdentityTable 
+ MapCollection 


new 













alllndexes isEmpty 
allltems items 

at, [] makeArray 
empty put, []- 
пазпдех remove 
hasitem removeltem 
index supplier 





Note: The IdentityTable class also has available class methods that its metaclass, the Class class, 
defines. It also inherits methods from the Map Collection class. 


5.3.17.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) “| instanceMethod send 


= \= == \== <> >< instanceMethods sendWith 
class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


Methods inherited from the Collection class. 
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П hasIndex put 

П- hasItem subset 
allIndexes index supplier 
allItems intersection union 


at items XOr 
difference makeArray 


Methods inherited from the MapCollection class. 


putAll 


5.3.17.2. new (Class Method) 


Returns an empty IdentityTable object. 


5.3.17.3. [] 


»»- [index]----------------------------------------------------- >< 


Returns the item associated with index. This is the same as the at() method. 


5.3.17.4. []- 


>>- [index]-item------------------------------------------------ >< 


Adds item to the table at index index. This method is the same as the put() method. 


5.3.17.5. alllndexes 


22»-allIndexes------------—-—---------nneceeece nee piece >< 


Returns an array of all indices contained in the table. 


5.3.17.6. allltems 


22-alUTtems---————-—-—----————— eMe SRS Se SSS SSS SS SSeS Sea >< 


Returns an array of all items contained in the table. 


5.3.17.7. at 


»»-at(index)--------------------------------------------------- >< 
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Returns the item associated with index index. Returns the Nil object if the collection has no item 
associated with index. 


5.3.17.8. empty 


>з-ешру---2-------------------- a -<< >< 


Removes all items from Ше table. 


5.3.17.9. hasIndex 


»»-hasIndex(index)--------------------------------------------- >< 


Returns 1 (true) if the collection contains any item associated with index index, or 0 (false). 


5.3.17.10. hasltem 


»»-hasItem(item)----------------------------------------------- >< 


Returns 1 (true) if the collection contains the item at any index position or otherwise returns 0 (false). 


5.3.17.11. index 


»»-index(item)------------------------------------------------- >< 


Returns the index of the specified item within the table. If the target item appears at more than one index, 
the first located index will be returned. Returns the Nil object if the table does not contain the specified 
item. 


5.3.17.12. isEmpty 


22 -1вЕпръу---<------------+--------<-<-+-+--<--------- >< 


Returns 1 (true) if Ше table is empty. Returns 0 (false) otherwise. 


5.3.17.13. items 


PP aT EONS i ll E E a E >< 


Returns the number of items in the collection. 
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5.3.17.14. makeArray 
Po sMAkGAT Tay == sss SSSR SS as SSS aa RS SSS SRST SS SRS RS SSR SS SSS piece >< 


Returns a single-index array containing the index objects. The array indexes range from 1 to the number 
of items. The collection items appear in the array in an unspecified order. 


5.3.17.15. put 
>>-put (item,index)--------------------------------------------- >< 


Makes the object item a member item of the collection and associates it with index index. The new item 
replaces any existing items associated with index index. 


5.3.17.16. remove 


»»-remove(index)----------------------------------------------- >< 


Returns and removes from a collection the member item with index index. Returns the Nil object if no 
item has index index. 


5.3.17.17. removeltem 
»»-removeltem(item)-------------------------------------------- >< 


Removes an item from the table. If the target item exists at more than one index, the first located item is 
removed. The return value is the removed item. 


5.3.17.18. supplier 


22o-Süppiier--------------—n-oecoo SSS SSS SS SSS SES SRS SRS SSS SSS Hs >< 


Returns a Supplier object for the collection. The supplier allows you iterate over the index/item pairs 
contained in the table at the time the supplier was created. The supplier iterates over the items in an 
unspecified order. 


5.3.18. Sorting Arrays 


Any non-sparse Array instance can have its elements placed into sorted order using the sort method of 
the Array class. The simplest sort is sorting an array of strings. For example: 


myArray = .array~of("Zoe", "Fred", "Xavier", "Andy") 
myArray~ sort 


do name over myArray 
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say name 
end 


will display the names in the order "Andy", "Fred", "Xavier", "Zoe". 


The sort method orders the strings by using the compareTo method of the String class. The compareTo 
method knows how to compare one string to another, and returns the values -1 (less than), 0 (equal), or 1 
(greater than) to indicate the relative ordering of the two strings. 


5.3.18.1. Sorting non-strings 


Sorting is not limited to string values. Any object that inherits the Comparable mixin class and 
implements a compareTo method can be sorted. The DateTime Class and TimeSpan Class are examples 
of built-in Rexx classes that can be sorted. Any user created class may also implement a compareTo() 
method to enable sorting. For example, consider the following simple class: 


::class Employee inherit Comparable 
::method init 

expose id name 

use arg id, name 
::method id attribute 
::method name attribute 
::method compareTo 

expose id 

use arg other 

return id^compareTo(other^id) -- comparison performed using employee id 
::method string 

expose name 

use arg name 

return "Employee" name 


The Employee class implements its sort order using the employee identification number. When the sort 
method needs to compare two Employee instances, it will call the compareTo method on one of the 
instances, passing the second instance as an argument. The compareTo method tells the sort method 
which of the two instances should be first. 


а = .array new 

a[1] = .Employee^new(654321, "Fred") 
a[2] = .Employee^new(123456, "George") 
a[3] = .Employee^new(333333, "William") 


a^sort 
do employee over a 


say employee -- sorted order is "George", "William", "Fred" 
end 


264 ooRexx Reference Version 4.0.0 


Chapter 5. The Builtin Classes 


5.3.18.2. Sorting with more than one order 


The String class compareTo method only implements a sort ordering for an ascending sort using a strict 
comparison. Frequently it’s desirable to override a class-defined sort order or even to sort items that do 
not implement a compareTo method. To change the sorting criteria, use the Array sortWith method. 
The sortWith method takes a single argument, which is a Comparator object that implements a compare 
method. The compare method performs comparisons between pairs of items. Different comparators can 
be customized for different comparison purposes. For example, the Rexx language provides a 
DescendingComparator class that will sort items into descending order: 


::CLASS ’?DescendingComparator’ MIXINCLASS Comparator 
::METHOD compare 

use strict arg left, right 

return -left~compareTo (right) 


The DescendingComparator merely inverts the result returned by the item compareTo method. Our 
previous example 


myArray = .array~of("Zoe", "Fred", "Xavier", "Andy") 
myArray^sortWith(.DescendingComparator^new) 


do name over myArray 
say name 
end 


now displays in the order "Zoe", "Xavier", "Fred", "Andy". 


Custom Comparators are simple to create for any sorting purpose. The only requirement is implementing 
a compare method that knows how to compare pairs of items in some particular manner. For example, to 
sort our Employee class by name instead of the default employee id, we can use the following simple 
comparator class: 


::CLASS EmployeeNameSorter MIXINCLASS Comparator 
::METHOD compare 
use strict arg left, right 
return left^name^compareTo(right^name) -- do the comparison using the names 


5.3.18.3. Builtin Comparators 


Rexx includes a number of built-in Comparators for common sorting operations. 


Comparator 


Base comparator. The Comparator class just uses the compareTo method of the first argument to 
generate the result. Using sortWith and a Comparator instance is equivalent to using the sort 
method and no comparator. 


DescendingComparator 


The reverse of the Comparator class. The DescendingComparator can be used to sort items in 
descending order. 
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InvertingComparator 


The InvertingComparator will invert the result returned by another Comparator instance. This 
comparator can be combined with another comparator instance to reverse the sort order. 


CaselessComparator 


Like the base comparator, but uses the caselessCompareTo method to determine order. The String 
class implements caselessCompareTo, so the CaselessComparator can be used to sort arrays of 
strings independent of case. 


ColumnComparator 


The ColumnComparator will sort string items using specific substrings within each string item. If 
sorting is performed on multiple column positions, the stableSortWith method is recommended to 
ensure the results of previous sort operations are retained. 


CaselessColumnComparator 


Like the ColumnComparator, but the substring comparisons are done independently of case. 


5.3.18.4. Stable and Unstable Sorts 


The default sorting algorithm is a Quicksort. A Quicksort is a very efficient sorting algorithm that does 
not require any additional memory to implement. Unfortunately, a Quicksort is also an unstable sort. In 
an unstable sort, items are not guaranteed to maintain their original positions if they compare equal 
during the sort. Consider the following simple example: 


a = .array~of("Fred", "George", "FRED", "Mike", "fred") 
a^sortwith(.caselesscomparator^new) 
do name over a 
say name 
end 


This example displays the 3 occurrences of Fred in the order "Fred", "fred", "FRED", even though they 
compare equal using a caseless comparison. 


The Array class implements a second sort algorithm that is available using the stableSort and 
stableSortWith methods. These methods use a Mergesort algorithm, which is less efficient than the 
default Quicksort and requires additional memory. The Mergesort is a stable algorithm that maintains the 
original relative ordering of equivalent items. Our example above, sorted with stableSortWith, would 
display "Fred", "FRED", "fred". 


5.3.19. The Concept of Set Operations 


The following sections describe the concept of set operations to help you work with set operators, in 
particular if the receiver collection class differs from the argument collection class. 


Rexx provides the following set-operator methods: 


* difference 
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* intersection 
* subset 

* union 

* xor 


These methods are available to instances of the following collection classes: 


* The OrderedCollections Array, List, and Queue 
* The MapCollections Directory, Stem, Table, and Relation 
* The SetCollections Set and Bag. 


result - receiver^setoperator(argument) 


where: 


receiver 


is the collection object receiving the set-operator message. 


setoperator 


is the set-operator method used. 


argument 


is the argument collection supplier supplied to the method. It can be an instance of one of the Rexx 
collection classes or any object that implements a makearray method or supplier method, 
depending on class of receiver. 


The result object is of the same class as the receiver collection object. 


5.3.19.1. The Principles of Operation 


A set operation is performed by iterating over the elements of the receiver collection to compare each 
element of the receiver with each element of the argument collection. The element is defined as the tuple 
< index,item> (see Determining the Identity of an Item). Depending on the set-operator method and the 
result of the comparison, an element of the receiver collection is, or is not, included in the resulting 
collection. A receiver collection that allows for duplicate elements can, depending on the set-operator 
method, also accept elements of the argument collection after they have been coerced to the type of the 
receiver collection. 


The following examples are to help you understand the semantics of set operations. The collections are 
represented as a list of elements enclosed in curly brackets. The list elements are separated by a comma. 


5.3.19.2. Set Operations on Collections without Duplicates 


Assume that the example sets are A={a,b} and B={b,c,d}. The result of a set operation is another set. 
The only exception is a subset resulting in a Boolean .true or .false. Using the collection A and B, the 
different set operators produce the following: 
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UNION operation 
All elements of A and B are united: 


A UNION B = {a,b,c,d} 


DIFFERENCE operation 


The resulting collection contains all elements of the first set except for those that also appear in the 
second set. The system iterates over the elements of the second set and removes them from the first 
set one by one. 


A DIFFERENCE B = {a} 
B DIFFERENCE A = {c,d} 
XOR operation 


The resulting collection contains all elements of the first set that are not in the second set and all 
elements of the second set that are not in the first set: 


A XOR B = {a,c,d} 


INTERSECTION operation 
The resulting collection contains all elements that appear in both sets: 


A INTERSECTION B = {b} 


SUBSET operation 


Returns .true if the first set contains only elements that also appear in the second set, otherwise it 
returns .false: 


A SUBSET B = .false 
B SUBSET A = .false 


5.3.19.3. Set-Like Operations on Collections with Duplicates 


Assume that the example bags are A={a,b,b} and B={b,b,c,c,d}. The result of any set-like operation is 
a collection, in this case a bag. The only exception is subset resulting in a Boolean .true or .false. Using 
the collections A and B, the different set-like operators produce the following: 


UNION operation 
All elements of A and B are united: 


A UNION B = {a,b,b,b,b,c,c,d} 


DIFFERENCE operation 


The resulting collection contains all elements of the first bag except for those that also appear in the 
second bag. The system iterates over the elements of the second bag and removes them from the 
first bag one by one. 


A DIFFERENCE B = {a} 
B DIFFERENCE A = {c,c,d} 
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XOR operation 


The resulting collection contains all elements of the first bag that are not in the second bag and all 
elements of the second bag that are not in the second bag: 


А XOR B = {a,c,c,d} 


INTERSECTION operation 


The resulting collection contains all elements that appear in both bags: 


A INTERSECTION B = {b,b} 


SUBSET operation 


Returns .true if the first set contains only elements that also appear in the second set, otherwise it 
returns .false: 


A SUBSET B = .false 
B SUBSET A = .false 


5.3.19.4. Determining the Identity of an Item 


Set operations require the definition of the identity of an element to determine whether a certain element 
exists in the receiver collection. The element of a collection is conceived as the tuple <index,item>. The 
index is used as the identification tag associated with the item. Depending on the collection class, the 
index is an instance of a particular class, for example, the string class for a directory element, an integer 
for an array, or any arbitrary class for a relation. The Array class is an exception because it can be 
multidimensional having more than one index. However, as a collection, it is conceptionally linearized 
by the set operator. 


For collection classes that require unique indexes, namely the Set, IdentityTable, Table, Directory, and 
Stem, an item is identified by its index. For collections of collection classes that allow several items to 
have the same index, namely the Relation class, an item is identified by both its index and its item. For 
the Bag and the Set subclasses, where several items can have the same index but index and item must be 
identical, the item is identified by its index. For Array, List, and Queue classes, the index is derived from 
an object’s position within the collection’s order. Items are identified using only item. 


When collections with different index semantics are used in set operations, the argument collection is 
coerced into a collection of the same type as the receiver, and the operation is then performed using the 
converted collection. The coercion process differs based on the types of both the receiver and the 
argument collection. According to this concept, an item of a collection is identified for the different 
receiver categories as follows: 


Map Collection 


If argument is a MapCollection, then index values are used to determine membership, and items are 
inserted into the result using the index and item pairs. 


If argument is an OrderedCollection or SetCollection, argument is converted into a MapCollection 
using the collection items as both index and item values. Since the argument collection may contain 
duplicate items, the converted collection is effectively a Relation instance. 


For all other argument objects, the makearray method is used to obtain a set of values which are 
used as if argument was an OrderedCollection. 
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Ordered Collection and Set Collection 


If argument is an instance of Collection, the matching set is obtained from the allItems method. For 
any other class of object, the makearray method is used. The hasItem method is used to perform 
the matching operations between the two collections. 


Relation 


If argument is a MapCollection, then index values are used to determine membership, and items are 
inserted into the result using the index and item pairs. 


If argument is an OrderedCollection or SetCollection, argument is converted into a MapCollection 
using the collection items as both index and item values. Since the argument collection may contain 
duplicate items, the converted collection is effectively a Relation instance. 


For all other argument objects, the makearray method is used to obtain a set of values which are 
used as if argument was an OrderedCollection. All tests for result membership are made using both 
the index and item values. 


5.4. The Utility Classes 


This section describes the Rexx utility classes. 


5.4.1. The DateTime Class 


A DateTime object represents a point in between | January 0001 at 00:00.000000 and 31 December 
9999 at 23:59:59.999999. A DateTime object has methods to allow formatting a date or time in various 
formats, as well as allowing arithmetic operations between dates. 
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Figure 5-28. The DateTime class and methods 
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Note: The DateTime class also has available class methods that its metaclass, the Class class, 
defines. 
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5.4.1.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) — instanceMethod send 


=\===\== <> >< instanceMethods sendWith 
class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


Methods inherited from the Comparable class. 


* compareTo 


Methods inherited from the Orderable class. 


=, \=, =, ЕЕ, <>, ><, >, <, >=, \<, <=, |», >>, <<, >> <<, <<, >> 


5.4.1.2. minDate (Class Method) 


aT YB 6 aaa aaa >< 


Returns a DateTime instance representing the minimum supported Rexx date, 1 January 0001 at 
00:00:00.000000. 


5.4.1.3. maxDate (Class Method) 


POSMARDAG OSs SSS SS SSR SS RRS SS RSH RS SSS SSS SSS SSS ESSER SS eeepc >< 


Returns a DateTime instance representing the maximum supported Rexx date, 31 December 9999 at 
23:59:59.999999. 


5.4.1.4. today (Class Method) 


Po SOD AY SSSR Ss SRS SSSR SSSR SRR RRS RS SSS SRST сн >< 


Returns a DateTime instance for the current day, with a time value of 00:00:00.000000. 


5.4.1.5. fromNormalDate (Class Method) 


»»-fromNormalDate(-date-4---------------------------- %-)------------- >< 
%-,-%----------- %--%--------- + 


+-separator-+ +-,offset-+ 


Creates a DateTime object from a string returned by the Normal option of the Date() built-in function. 
The time component will be set to the beginning of the input day (00:00:00.000000). 
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If specified, separator identifies the field separator character used in the string. The separator must be a 
single character or the null string (""). A blank (" ") is the default separator. 


"on 


If specified, offset is the offset from UTC, in minutes. The offset must be valid whole number value. The 
default offset is the current system offset timezone offset. 


5.4.1.6. fromEuropeanDate (Class Method) 


»»-fromEuropeanDate(-date-4---------------------------- %--)------------ >< 
%-,-%----------- %--%--------- + 


+-separator-+ +-,offset-+ 


Creates a DateTime object from a string returned by the European option of the Date() built-in function. 
The time component will be set to the beginning of the input day (00:00:00.000000). 


If specified, separator identifies the field separator character used in the string. The separator must be a 
single character or the null string (""). A slash ("/") is the default separator. The time component will be 
set to the beginning of the input day (00:00:00.000000). 


If specified, offset is the offset from UTC, in minutes. The offset must be valid whole number value. The 
default offset is the current system offset timezone offset. 


5.4.1.7. fromOrderedDate (Class Method) 


»»-fromÜrderedDate(-date-4---------------------------- %--)------------ >< 
%-,-%----------- %--%--------- + 


+-separator-+ +-,offset-+ 
Creates a DateTime object from a string returned by the Ordered option of the Date() built-in function. 
The time component will be set to the beginning of the input day (00:00:00.000000). 


If specified, separator identifies the field separator character used in the string. The separator must be a 
single character or the null string (""). A slash ("/") is the default separator. The time component will be 
set to the beginning of the input day (00:00:00.000000). 


If specified, offset is the offset from UTC, in minutes. The offset must be valid whole number value. The 
default offset is the current system offset timezone offset. 


5.4.1.8. fromStandardDate (Class Method) 


»»-fromStandardDate(-date-4---------------------------- %--)------------ >< 
%-,-%----------- %--%--------- + 


*-separator-* +-,offset-+ 


Creates a DateTime object from a string returned by the Standard option of the Date() built-in function. 
The time component will be set to the beginning of the input day (00:00:00.000000). 


If specified, separator identifies the field separator character used in the string. The separator must be a 
single character or the null string (""). A null string ("") is the default separator. 
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If specified, offset is the offset from UTC, in minutes. The offset must be valid whole number value. The 
default offset is the current system offset timezone offset. 


5.4.1.9. fromUsaDate (Class Method) 


»»-fromUsaDate(-date-4---------------------------- %--)------------ >< 
%-,-%----------- %--%--------- + 


+-separator-+ +-,offset-+ 
Creates a DateTime object from a string returned by the Usa option of the Date() built-in function. The 
time component will be set to the beginning of the input day (00:00:00.000000). 


If specified, separator identifies the field separator character used in the string. The separator must be a 
single character or the null string (""). A slash ("/") is the default separator. 


If specified, offset is the offset from UTC, in minutes. The offset must be valid whole number value. The 
default offset is the current system offset timezone offset. 


5.4.1.10. fromNormalTime (Class Method) 


>>-fromNormalTime (time--4--------- %-)------------------------ >< 
+-,offset-+ 


Creates a DateTime object from a string returned by the Normal option of the Time() built-in function. 
The date component will be set to 1 January 0001. 


If specified, offset is the offset from UTC, in minutes. The offset must be valid whole number value. The 
default offset is the current system offset timezone offset. 


5.4.1.11. fromCivilTime (Class Method) 


»»-fromCivilTime(time--4--------- %-)------------------------ >< 
+-,offset-+ 


Creates a DateTime object from a string returned by the Civil option of the Time() built-in function. The 
date component will be set to 1 January 0001. 


If specified, offset is the offset from UTC, in minutes. The offset must be valid whole number value. The 
default offset is the current system offset timezone offset. 


5.4.1.12. fromLongTime (Class Method) 


>>-fromLongTime (time--+--------- %-)------------------------ >< 
+-,offset-+ 


Creates a DateTime object from a string returned by the Long option of the Time() built-in function. The 
date component will be set to 1 January 0001. 
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If specified, offset is the offset from UTC, in minutes. The offset must be valid whole number value. The 
default offset is the current system offset timezone offset. 


5.4.1.13. fromBaseDate (Class Method) 


>>-fromBaseDate (date--+--------- %-)------------------------------- >< 
+-,offset-+ 


Creates a DateTime object from a string returned by the Basedate option of the Date() built-in function. 
The time component will be set to the beginning of the input day (00:00:00.000000). 


If specified, offset is the offset from UTC, in minutes. The offset must be valid whole number value. The 
default offset is the current system offset timezone offset. 


5.4.1.14. fromTicks (Class Method) 


»»-fromTicks(time--4--------- %-)-------------------------- >< 
+-,offset-+ 


Creates a DateTime object from a string returned by the Ticks option of the Date() or Time() built-in 
functions. 


If specified, offset is the offset from UTC, in minutes. The offset must be valid whole number value. The 
default offset is the current system offset timezone offset. 


5.4.1.15. fromlsoDate (Class Method) 


»»-fromIsoDate(date--4--------- %-)------------------------ >< 
+-,offset-+ 


Creates a DateTime object from a string in ISO date format (yyyy-mm-ddThh:mm:ss.uuuuuu). The 
DateTime string method returns the ISO format as the string form of a DateTime object. 


If specified, offset is the offset from UTC, in minutes. The offset must be valid whole number value. The 
default offset is the current system offset timezone offset. 


5.4.1.16. fromUTCIsoDate (Class Method) 


»»-fromUTCIsoDate(date)-------------------------------------- >< 


Creates a DateTime object from a string in ISO timezone qualified date format 
(yyyy-mm-ddThh:mm:ss.uuuuuu--hhmm). The DateTime string method returns the ISO format as the 
string form of a DateTime object. 
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5.4.1.17. init 


>>-іпі%-------------------------------------------------------- >< 


>>-init (fullDate--+--------- 4-)----сас-----ч-аз-а--т-зЭеЗ-Ш---- >< 
+-,offset-+ 


»»-init(year,month,day-4--------- аа %---->< 
+-,offset-+ 


»»-init(year,month,day,hours,minutes,seconds--4-------------------------------- %-)->< 
%-,-%-------------- %-%--------- +-+ 


+-microseconds-+ +-,offset-+ 


Initializes a new DateTime instance. If no arguments are specified, the DateTime instance is set to the 
current date and time. If the single fullDate argument is used, the DateTime argument is initialized to the 
date and time calculated by adding fullDate microseconds to 0001-01-01T00:00:00.000000. If the year, 
month, day, form is used, the DateTime instance is initialized to 00:00:00.000000 on the indicated date. 
Otherwise, the DateTime instance is initialized to the year, month, day, hours, minutes, seconds, and 
microseconds components. Each of these components must be a valid whole number within the 
acceptable range for the given component. For example, year must be in the range 1-9999, while minutes 
must be in the range 0-59. 


If specified, offset is the offset from UTC, in minutes. The offset must be valid whole number value. The 
default offset is the current system offset timezone offset. 


Examples: 


today = .DateTime^new -- initializes to current date and time 
-- initializes to 9 Sep 2007 at 00:00:00.000000 
day = .DateTime~new(date(’F’, "20070930", "S")) 
-- also initializes to 9 Sep 2007 at 00:00:00.000000 
.DateTime~new(2007, 9, 30) 
-- initializes to 9 Sep 2007 at 10:33:00.000000 
day = .DateTime^new(2007, 9, 30, 10, 33, 00) 


day 


5.4.1.18. Arithmetic Methods 


»»-arithmetic, operator (argument)------------------------------- >< 


Note: For the prefix + operators, omit the parentheses and argument. 


Returns the result of performing the specified arithmetic operation on the receiver DateTime object. 
Depending on the operation, the argument be either a TimeSpan object or a DateTime object. See the 
description of the individual operations for details. The arithmetic_operator can be: 
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+ Addition. Adds a TimeSpan to the DateTime object, returning a new DateTime 
instance. The receiver DateTime object is not changed. The TimeSpan may be 
either positive or negative. 


- Subtraction. If argument is a DateTime object, the two times are subtracted, and a 
TimeSpan object representing the interval between the two times is returned. If 
the receiver DateTime is less than the argument argument DateTime, a negative 
TimeSpan interval is returned. The receiver DateTime object is not changed. 

If argument is a TimeSpan object, subtracts the TimeSpan from the DateTime 
object, returning a new DateTime instance. The receiver DateTime object is not 
changed. The TimeSpan may be either positive or negative. 


Prefix - A prefix - operation on a DateTime object will raise a SYNTAX error condition. 
Prefix + Returns a new instance of the DateTime object with the same time value. 
Examples: 

t = .dateTime^newtimeO0fDay -- returns TimeSpan for current time. 

say t -- displays "11:27:12.437000", perhaps 

d = .dateTime^new(2010, 4, 11) -- creates new date 

future = а + + -- adds timespan to а 

say future -- displays "2010-04-11T11:27:12.437000" 


-- "real" start of next century 
nextCentury = .dateTime^new(2101, 1, 1) 


-- displays "34060.12:25:49.922000", perhaps 
say "The next century starts in" (nextCentury - .dateTime^new) 


5.4.1.19. compareTo 


»»-compareTo(other)------------------------------------------------ >< 


This method returns "-1" if the other is larger than the receiving object, "0" if the two objects are equal, 
and "1" if other is smaller than the receiving object. 


5.4.1.20. year 


Returns the year represented by this DateTime instance. 


5.4.1.21. month 


> SMW haa Sa eS Sa SS Se >< 


Returns the month represented by this DateTime instance. 
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5.4.1.22. day 


Returns the day represented by this DateTime instance. 


5.4.1.23. hours 


Returns number of whole hours since midnight. 


5.4.1.24. minutes 


Po SMI Nt es = Ss lS SSS SSeS a SS SS a Sees >< 


Returns minutes portion of the timestamp time-of-day. 


5.4.1.25. seconds 


oea e loe V- Se SSS нына >< 


Returns seconds portion of the timestamp time-of-day. 


5.4.1.26. microseconds 


>>-ш1сговесопдв-----------#-----------------+#---- - + >< 


Returns microseconds portion of the timestamp time-of-day. 


5.4.1.27. dayMinutes 


>> дауМпивев---- ee Se >< 


Returns the number of minutes since midnight in the time-of-day. 


5.4.1.28. daySeconds 


oo -dayos Conds = sas Gass sss ssa 99 rsa SS esses esses ee >< 


Returns the number of seconds since midnight in the time-of-day. 
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5.4.1.29. dayMicroseconds 
>> -дауМъстовесопдв---------------#-------3----<----+---# + -< >< 


Returns Ше number of microseconds since midnight in Ше time-of-day. 


5.4.1.30. hashCode 
ao -павпСоде------ Sa = SS se eae aoe >< 


Returns a string value that is used as a hash value for a MapCollection such as Table, Relation, Set, Bag, 
and Directory. 


5.4.1.31. addYears 
»»-addYears(years)-------------------------------------------- >< 


Add а number of years to the DateTime object, returning a new DateTime instance. Тһе receiver 
DateTime object is unchanged. The years value must be a valid whole number. Negative values result in 
years being subtracted from the DateTime value. 


The addYears method will take leap years into account. If the addition result would fall on February 29th 
of anon-leap year, the day will be rolled back to the 28th. 


date = .DateTime^new(2008, 2, 29) 


say date -- Displays "2008-02-29T00:00:00.000000" 
say date^addYears(1) -- Displays "2009-02-29T00:00:00.000000" 
5.4.1.32. addWeeks 

»»-addWeeks (weeks)------------------------------------------ >< 


Adds weeks to the DateTime object, returning a new DateTime instance. The receiver DateTime object is 
unchanged. The weeks value must be a valid number, including fractional values. Negative values result 
in week being subtracted from the DateTime value. 


5.4.1.33. addDays 
>>-addDays (days)-------------------------------------------- >< 


Adds days to the DateTime object, returning a new DateTime instance. The receiver DateTime object is 
unchanged. The days value must be a valid number, including fractional values. Negative values result in 
days being subtracted from the DateTime value. 


date = .DateTime^new(2008, 2, 29) 
say date -- Displays "2008-02-29T00:00:00.000000" 
say date^addDays(1.5) -- Displays "2008-03-01T12:00:00.000000" 
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5.4.1.34. addHours 
>>-addHours (hours)------------------------------------------ >< 


Adds hours to the DateTime object, returning a new DateTime instance. The receiver DateTime object is 
unchanged. The hours value must be a valid number, including fractional values. Negative values result 
in hours being subtracted from the DateTime value. 


5.4.1.35. addMinutes 


>>-addMinutes (minutes)-------------------------------------- >< 


Adds minutes to the DateTime object, returning a new DateTime instance. Тһе receiver DateTime object 
is unchanged. The minutes value must be a valid number, including fractional values. Negative values 
result in minutes being subtracted from the DateTime value. 


5.4.1.36. addSeconds 


»»-addSeconds(seconds)-------------------------------------- >< 


Adds seconds to the DateTime object, returning a new DateTime instance. Тһе receiver DateTime object 
is unchanged. The seconds value must be a valid number, including fractional values. Negative values 
result in seconds being subtracted from the DateTime value. 


5.4.1.37. addMicroseconds 
>>-addMicroseconds (microseconds)---------------------------- >< 


Adds microseconds to the DateTime object, returning a new DateTime instance. The receiver DateTime 
object is unchanged. The microseconds value must be a valid whole number. Negative values result in 
microseconds being subtracted from the DateTime value. 


5.4.1.38. isoDate 


ape 1) = > aaa aaa aa в >< 


Returns a String formatted into ISO date format, yyyy-dd-mmThh:mm:ss.uuuuuu. 


5.4.1.39. utclsoDate 


22-utcIsoDateée--.———--———--——- uec Umm >< 


Returns a String formatted into a fully qualified ISO date format. If the timezone offiset is 0, the format 
is yyyy-dd-mmThh:mm:ss.uuuuuuZ. If the offset is positive, the date is formatted as 
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yyyy-dd-mmThh:mm:ss.uuuuuu+hhmm. If the offset is negative, the result will be in the format 
yyyy-dd-mmThh:mm:ss.uuuuuu-hhmm. 


5.4.1.40. baseDate 


>23-Бавейаве-------------- аана >< 


Returns Ше number of complete days (that is, not including Ше current day) since and including the base 
date, 1 January 0001, in the format: dddddd (no leading zeros or whitespace characters). 


The base date of 1 January 1970 is determined by extending the current Gregorian calendar backward 
(365 days each year, with an extra day every year that is divisible by 4 except century years that are not 
divisible by 400. It does not take into account any errors in the calendar system that created the 
Gregorian calendar originally. 


5.4.1.41. yearDay 


>2-уваграу------------------ ------+--<+- + >< 


Returns Ше number of days, including Ше current day, that have passed in the DateTime year in Ше 
format ddd (no leading zeros or blanks). 


5.4.1.42. weekDay 


>2-пеекВау----------+--+------ S >< 


Returns Ше day of Ше week, as an integer. The values returned use Ше ISO convention for day 
numbering. Monday is "1", Tuesday is "2", running through "7" for Sunday. 


5.4.1.43. europeanDate 


»»-europeanDate(-4----------- %-)------------------------------- >< 
+-верагатог-+ 


Returns Ше date in Ше format dd/mm/yy. If specified, separator identifies the field separator character 
used in the returned date. The separator must be a single character or the null string (""). A slash ("/") is 
the default separator. 


5.4.1.44. languageDate 
>2-ТаприареВае---------Е 5 ---- та 9а- +н ят 95 я >< 
Returns Ше date in ап implementation- and language-dependent, or local, date format. The format is dd 


month yyyy. The name of the month is according to the national language installed on the system. If no 
local date format is available, the default format is returned. 
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Note: This format is intended to be used as a whole; Rexx programs must not make any 
assumptions about the form or content of the returned string. 


5.4.1.45. monthName 


>2-попнНаше--------------------<- Saas See >< 


Returns the name of the DateTime month, in English. 


5.4.1.46. dayName 


>2-дауНаше-------------- SS SS Sa SSR >< 


Returns the name of the DateTime day, in English. 


5.4.1.47. normalDate 


>>-normalDate(-+----------- Ж) aaa >< 
+-верагатог-+ 


Returns Ше date in Ше format dd mon уууу. If specified, separator identifies Ше field separator character 
used in the returned date. The separator must be a single character or the null string (""). A blank (" ") is 
the default separator. 


5.4.1.48. orderedDate 


»»-orderedDate(-4----------- Td-j--—--—e----4s--eR-B-------R---—— >< 
+-separator-+ 


Returns the date in the format yy/mm/dd. If specified, separator identifies the field separator character 
used in the returned date. The separator must be a single character or the null string (""). A slash ("/") is 
the default separator. 


5.4.1.49. standardDate 


»»-standardDate(-4----------- %-)------------------------------- >< 
+-верагатог-+ 


Returns Ше date in Ше format yyyymmdd. If specified, separator identifies Ше field separator character 
). A null string 


пи 


used in Ше returned date. The separator must be a single character or the null string ( 
("") is the default separator. 


302 ooRexx Reference Version 4.0.0 


Chapter 5. The Builtin Classes 


5.4.1.50. usaDate 


»»-usaDate(-4----------- %-)------------------------------- >< 
+-верагатог-+ 


Returns Ше date in Ше format mm/dd/yy. If specified, separator identifies Ше field separator character 
used in the returned date. The separator must be a single character or the null string (""). A slash ("/") is 
the default separator. 


5.4.1.51. civilTime 


23- с оше --- eS euge аа --- >< 


Returns the time in Civil format hh:mmxx. The hours can take Ше values 1 through 12, and Ше minutes 
the values 00 through 59. The minutes are followed immediately by the letters am or pm. This 
distinguishes times in the morning (12 midnight through 11:59 a.m.--appearing as 12:00am through 
11:59am) from noon and afternoon (12 noon through 11:59 p.m.--appearing as 12:00pm through 
11:59pm). The hour has no leading zero. The minute field shows the current minute (rather than the 
nearest minute) for consistency with other TIME results. 


5.4.1.52. normalTime 


2>- normal Time === ао ee >< 


Returns the time in the default format hh:mm:ss. The hours can have the values 00 through 23, and 
minutes and seconds, 00 through 59. There are always two digits. Any fractions of seconds are ignored 
(times are never rounded). This is the default. 


5.4.1.53. longTime 


22 slong Time Sosa еее re CS eae ранена >< 


Returns time in the format hh:mm: ss.uuuuuu (where uuuuuu are microseconds). 


5.4.1.54. fullDate 


> ер TU Dat er SS >< 


Returns the number of microseconds since 00:00:00.000000 on 1 January 0001, in the format: 
dddddddddddddddddd (no leading zeros or blanks). 


5.4.1.55. utcDate 


23-шрсраве------------------------<--- >< 
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Returns the date converted to UTC time as the number of microseconds since 00:00:00.000000 on 1 
January 0001, in the format: dddddddddddddddddd (no leading zeros or blanks). 


5.4.1.56. toTimeZone 


»»-toTimeZone(-4-------- %-)------------------------------ >< 
+-offset-+ 


Returns a new DateTime object representing the time for the timezone indicated by offset. If specified, 
offset is the offset from UTC, in minutes. The offset must be valid whole number value. The default offset 
0, which creates a DateTime object for UTC. 


5.4.1.57. ticks 


POT ULCKS ат ee ee ee PEE >< 


returns the number of seconds since 00:00:00.000000 on 1 January 1970, in the format: dddddddddddd 
(no leading zeros or blanks). Times prior to 1 January 1970 are returned as a negative value. 


5.4.1.58. offset 


DP DOLI SOU a sea Fa ae SSS SS SS a SSR >< 


Returns the timezone for the DateTime instance as the offset in minutes from UTC. Timezones east of 
UTC will return a positive offset. Timezones west of UTC will return a negative offset. 


5.4.1.59. date 


»»-date--------------------------------------------------- >< 


Returns a new DateTime object instance for the current date, with the time component set to 
00:00:00.000000. 


5.4.1.60. timeOfDay 


>2-1 пей Шау----------- a eS SS SS Sea SSeS >< 


Returns the interval since 00:00:00.000000 of the current day as a TimeSpan object. 


5.4.1.61. elapsed 


PPA Lapsed ass SS е саат aS Sa аа oases >< 
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Returns the difference between current time and the receiver DateTime as a TimeSpan object. The 
TimeSpan will be negative if the receiver DateTime represents a time in the future. 


5.4.1.62. isLeapyear 


22-1 SL6apy Gar -- ааа аас >< 


Returns true ("1") if the current year is leap year. Returns false ("0") if the current year is not a leap year. 


5.4.1.63. daysinMonth 


2o-daysinMonth?=—ss SS - ss e SSS SS asa - >< 


Returns the number of days in the current month. For example, for dates in January, 31 is returned. The 
daysInMonth method takes leap years into account, returning 28 days for February in non-leap years, 
and 29 days for leap years. 


5.4.1.64. daysinYear 


eo days InYéars === Se SS sa >< 


Returns the number of days in the current year. For leap years, 366 is returned. For non-leap years, this 
returns 365. 


5.4.1.65. string 


2ревъшира------ ee SS SS >< 


Returns DateTime formatted as a string. The string value is returned in ISO format. 


5.4.2. The Alarm Class 


An alarm object provides timing and notification capability by supplying a facility to send any message 
to any object at a given time. You can cancel an alarm before it sends its message. 
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Figure 5-29. The Alarm class and methods 
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Note: The Alarm class also has available class methods that its metaclass, the Class class, defines. 


5.4.2.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) — instanceMethod send 
=\===\== <> >< instanceMethods sendWith 


class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


5.4.2.2. cancel 


Ban OT aaa a aaa >< 


Cancels the pending alarm request represented by the receiver. This method takes no action if the 
specified time has already been reached. 


5.4.2.3. init 


»»-init(atime,message)----------------------------------------- >< 


Sets up an alarm for a future time atime. At this time, the alarm object sends the message that message, a 
message object, specifies. (See The Message Class.) The atime can a String, DateTime object, or 
TimeSpan object. 


If atime is a DateTime object, the DateTime specifies a time when the alarm will be triggered. The 
DateTime must be greater than the current time. 
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If atime is a TimeSpan, the Alarm will be set to the current time plus the TimeSpan. The TimeSpan must 
not be a negative interval. 


If atime is a String, you can specify this as a date and time ('hh:mm:ss') or as a number of seconds 
starting at the present time. If you use the date and time format, you can specify a date in the default 
format ('dd Mmm yyyy') after the time with a single blank separating the time and date. Leading and 
trailing whitespace characters are not allowed in the atime. If you do not specify a date, the Alarm uses 
the first future occurrence of the specified time. You can use the cancel() method to cancel a pending 
alarm. See Initialization for more information. 


5.4.2.4. Examples 


The following code sets up an alarm at 5:10 p.m. on December 15, 2007. (Assume today’s date/time is 
prior to December 15, 2007.) 


/* Alarm Examples */ 


PersonalMessage-.MyMessageClass^new("Call the Bank") 
msg-.message^new(PersonalMessage, "RemindMe") 


time = .DateTime^fromIsoDate("2007-12-15T17:10:00.000000") 


a-.alarm^new(time, msg) 

exit 

::class MyMessageClass public 

::method init 

expose inmsg 

use arg inmsg 

::method RemindMe 

expose inmsg 

say "It is now" "TIME"("C")".Please "inmsg 

/* On the specified data and time, displays the following message: */ 
/* "It is now 5:10pm. Please Call the Bank" */ 


For the following example, the user uses the same code as in the preceding example to define msg, a 
message object to run at the specified time. The following code sets up an alarm to run the msg message 
object in 30 seconds from the current time: 


a-.alarm^new(30,msg) 


5.4.3. The TimeSpan Class 


A TimeSpan object represents a point in between 1 January 0001 at 00:00.000000 and 31 December 
9999 at 23:59:59.999999. A TimeSpan object has methods to allow formatting a date or time in various 
formats, as well as allowing arithmetic operations between dates. 
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Figure 5-30. The TimeSpan class and methods 
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Note: The TimeSpan class also has available class methods that its metaclass, the Class class, 
defines. 


5.4.3.1. Inherited Methods 
Methods inherited from the Object class. 


new (class method) “| instanceMethod send 
=\===\== <> >< instanceMethods sendWith 
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class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


Methods inherited from the Comparable class. 


* compareTo 


Methods inherited from the Orderable class. 


Bi. ===, «уна o e Xu im ЗО 6 uem КФ v Се 


5.4.3.2. fromDays (Class Method) 
>>-fromDays (days)-------------------------------------------- >< 


Creates a TimeSpan object from a number of days. The days argument must be a valid Rexx number. 


5.4.3.3. fromHours (Class Method) 


>>-fromHours (hours)------------------------------------------ >< 


Creates a TimeSpan object from a number of hours. The hours argument must be a valid Rexx number. 


5.4.3.4. fromMinutes (Class Method) 


>>-fromMinutes (minutes)-------------------------------------- >< 


Creates a TimeSpan object from a number of minutes. The minutes argument must be a valid Rexx 
number. 


5.4.3.5. fromSeconds (Class Method) 


>>-fromSeconds (seconds)-------------------------------------- >< 


Creates a TimeSpan object from a number of seconds. The seconds argument must be a valid Rexx 
number. 


5.4.3.6. fromMicroseconds (Class Method) 


>>-fromMicroseconds (microseconds)--------------------------------- >< 


Creates a TimeSpan object from a number of microseconds. The microseconds argument must be a valid 
Rexx number. 
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5.4.3.7. fromNormalTime (Class Method) 
>>-fromNormalTime (time)---------------------------------------------- >< 


Creates а TimeSpan object from а string returned by the Normal option of the Time() built-in function. 
The TimeSpan will contain an interval equal to the time of day represented by the string. 


5.4.3.8. fromCivilTime (Class Method) 


»»-fromCivilTime(time)---------------------------------------- >< 


Creates a TimeSpan object from a string returned by the Civil option of the Time() built-in function. The 
TimeSpan will contain an interval equal to the time of day represented by the string. 


5.4.3.9. fromLongTime (Class Method) 


>>-fromLongTime (time)---------------------------------------- >< 


Creates a TimeSpan object from a string returned by the Long option of the Time() built-in function. The 
TimeSpan will contain an interval equal to the time of day represented by the string. 


5.4.3.10. fromStringFormat (Class Method) 


>>-fromStringFormat (time)------------------------------------ >< 


Creates a TimeSpan object from a string in the format returned by the TimeSpan string method. 


5.4.3.11. init 


»»-init(fullDate)--------------------------------------------- >< 
>>-init (hours, minutes, seconds)------------------------------ >< 
>>-init(day, hours, minutes, second, microseconds) ------------ >< 


Initializes a new TimeSpan instance. If the single fullDate argument is used, the TimeSpan argument is 
initialized to the time span fullDate microseconds. Otherwise, the TimeSpan instance is initialized to 
either the hours, minutes, and seconds or the days, hours, minutes, seconds, and microseconds 
components. Each of these components must be a valid whole number within the acceptable range for 
the given component. For example, hours must be in the range 0-23, while minutes must be in the range 
0-59. 


Examples: 
-- initializes to 15 hours, 37 minutes and 30 seconds 
-- (15:37:30.000000) 


span = .TimeSpan~new(time(’F’, "15:37:30", "N)) 
-- also initializes to 15:37:30.000000 
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span = .TimeSpan^new(15, 37, 30) 
-- initializes to 6.04:33:15.000100 
span = .TimeSpan^new(6, 4, 33, 15, 100) 


5.4.3.12. Arithmetic Methods 


>>-arithmetic_operator (argument ) ------------------------------- >< 


Note: For the prefix + operators, omit the parentheses and argument. 


Returns the result of performing the specified arithmetic operation on the receiver TimeSpan object. 
Depending on the operation, the argument be either a TimeSpan object, a DateTime object, or a number. 
See the description of the individual operations for details. The arithmetic_operator can be: 


+ Addition. If argument is a DateTime object, the TimeSpan is added to the 
DateTime object, returning a new DateTime instance. Neither the receiver 
TimeSpan or the argument DateTime object is altered by this operation. The 
TimeSpan may be either positive or negative. 
If argument is a TimeSpan object, the two TimeSpans are added together, and a 
new TimeSpan instance is returned. Neither the TimeSpan object is altered by 
this operation. 


- Subtraction. The argument must be a TimeSpan object. The argument TimeSpan 
is subtracted from the receiver TimeSpan and a new TimeSpan instance is 
returned. Neither the TimeSpan object is altered by this operation. 

Т Multiplication. The argument must be a valid Rexx number. Тһе TimeSpan is 
multiplied by the argument value, and a new TimeSpan instance is returned. The 
receiver TimeSpan object is not altered by this operation. 

/ Division. The argument must be a valid Rexx number. The TimeSpan is divided 
by the argument value, and a new TimeSpan instance is returned. The receiver 
TimeSpan object is not altered by this operation. The / operator and % produce the 
same result. 

% Integer Division. The argument must be a valid Rexx number. The TimeSpan is 
divided by the argument value, and a new TimeSpan instance is returned. The 
receiver TimeSpan object is not altered by this operation. The / operator and % 
produce the same result. 

// Remainder Division. The argument must be a valid Rexx number. The TimeSpan 
is divided by the argument value and the division remainder is returned as a new 
TimeSpan instance. The receiver TimeSpan object is not altered by this operation. 


Prefix - The TimeSpan is negated, returning a new TimeSpan instance. The receiver 
TimeSpan is not altered by this operation. 

Prefix + Returns a new instance of the TimeSpan object with the same time value. 

Examples: 
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ti = .timespan~fromHours(1) 
12 = 11 * 2 


-- displays "01:00:00.000000 01:30:00.000000 02:30:00.000000" 
say t1 t2 (t1 + t2) 


5.4.3.13. compareTo 


»»-compareTo(other)------------------------------------------------ >< 


" " 


This method returns if the other is larger than the receiving object, "0" if the two objects are equal, 


and "1" if other is smaller than the receiving object. 


5.4.3.14. duration 


>>= duration ae ee eS aS іле етсе + ----- << -- >< 


Returns a new TimeSpan object containing the absolute value of the receiver TimeSpan object. 


5.4.3.15. days 


Returns the number of whole days in the TimeSpan, as a positive number. 


5.4.3.16. hours 


2> hours дӣ >< 


Returns the hours component of the TimeSpan, as a positive number. 


5.4.3.17. minutes 


>2-шишез--------+- E a E EE E ++ >< 


Returns the minutes component of the TimeSpan, as a positive number. 


5.4.3.18. seconds 


22-весопав--------------+----+- SSS a a aS Se Se SSeS SaaS >< 


Returns the seconds component of the TimeSpan, as a positive number. 
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5.4.3.19. microseconds 
>>-шъсговесопдв---------- Saas Sse Se SSeS алата eS SS See cass >< 


Returns the microseconds component of the TimeSpan, as a positive number. 


5.4.3.20. totalDays 


22-UtotalDays---—— ананан eae >< 


Returns the time span expressed as a number of days. The result includes any fractional part and retains 
the sign of the receiver TimeSpan. 


5.4.3.21. totalHours 


222UOta4tHOl$S-cL————— Uu RII a ee ee VE >< 


Returns the time span expressed as a number of hours. The result includes any fractional part and retains 
the sign of the receiver TimeSpan. 


5.4.3.22. totalMinutes 


22-рорапивев--- ята ааа SSS >< 


Returns Ше time span expressed as а number of minutes. The result includes any fractional part and 
retains the sign of the receiver TimeSpan. 


5.4.3.23. totalSeconds 


>> totalLSeCond se Sa >< 


Returns the time span expressed as a number of seconds. The result includes any fractional part and 
retains the sign of the receiver TimeSpan. 


5.4.3.24. totalMicroseconds 


2o-totalMicroseconds=—= +35 не SSeS eS ae >< 


Returns the time span expressed as a number of microseconds. The result retains the sign of the receiver 
TimeSpan. 


5.4.3.25. hashCode 


>2-наврСоде------ a Se >< 
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Returns a string value that is used as a hash value for MapCollection such as Table, Relation, Set, Bag, 
and Directory. 


5.4.3.26. addWeeks 


>>-addWeeks (weeks)------------------------------------------ >< 


Adds weeks to the TimeSpan object, returning a new TimeSpan instance. The receiver TimeSpan object 
is unchanged. The weeks value must be a valid number, including fractional values. Negative values 
result in week being subtracted from the TimeSpan value. 


5.4.3.27. addDays 
>>-addDays (days)-------------------------------------------- >< 


Adds days to the TimeSpan object, returning a new TimeSpan instance. Тһе receiver TimeSpan object is 
unchanged. The days value must be a valid number, including fractional values. Negative values result in 
days being subtracted from the TimeSpan value. 


5.4.3.28. addHours 


>>-addHours (hours)------------------------------------------ >< 


Adds hours to the TimeSpan object, returning a new TimeSpan instance. The receiver TimeSpan object is 
unchanged. The hours value must be a valid number, including fractional values. Negative values result 
in hours being subtracted from the TimeSpan value. 


5.4.3.29. addMinutes 


>>-addMinutes (minutes)-------------------------------------- >< 


Adds minutes to the TimeSpan object, returning a new TimeSpan instance. Тһе receiver TimeSpan 
object is unchanged. The minutes value must be a valid number, including fractional values. Negative 
values result in minutes being subtracted from the TimeSpan value. 


5.4.3.30. addSeconds 


»»-addSeconds(seconds)-------------------------------------- >< 


Adds seconds to the TimeSpan object, returning а new TimeSpan instance. Тһе receiver TimeSpan 
object is unchanged. The seconds value must be a valid number, including fractional values. Negative 
values result in seconds being subtracted from the TimeSpan value. 


314 ooRexx Reference Version 4.0.0 


Chapter 5. The Builtin Classes 
5.4.3.31. addMicroseconds 
>>-addMicroseconds (microseconds)---------------------------- >< 


Adds microseconds to the TimeSpan object, returning a new TimeSpan instance. The receiver TimeSpan 
object is unchanged. The microseconds value must be a valid whole number. Negative values result in 
microseconds being subtracted from the TimeSpan value. 


5.4.3.32. sign 


Returns "-1" if the TimeSpan is negative, "1" if the TimeSpan is positive, and "0" if the TimeSpan 
duration is zero. 


5.4.3.33. string 
>2-зъшир-----<-<---------- a E >< 


Returns TimeSpan formatted as a string. The string value is in the format 
"-dddddddd.hh:mm:ss.uuuuuu". If the TimeSpan is positive or zero, the sign is omitted. The days field 
will be formatted without leading zeros or blanks. If the TimeSpan duration is less than a day, the days 
field and the period separator will be omitted. 


5.4.4. The Comparable Class 


This class is defined as a mixin class. 


Figure 5-31. The Comparable class and methods 
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Note: The Comparable class also has available class methods that its metaclass, the Class class, 
defines. 
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5.4.4.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) instanceMethod send 
=\===\== <> >< instanceMethods sendWith 


class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


5.4.4.2. compareTo 
This method compares the receiving object to the object supplied in the comparable argument. 
»»-compareTo(other)--------------------------------------- >< 


" " 


This method returns if the other is larger than the receiving object, "0" if the two objects are equal, 
and "1" if other is smaller than the receiving object. 


5.4.5. The Orderable Class 


The Orderable class can be inherited by classes which wish to provide each of the comparison operator 
methods without needing to implement each of the individual methods. The inheriting class need only 
implement the Comparable compareTo() method. See This class is defined as a mixin class. 


Figure 5-32. The Orderable class and methods 
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5.4.5.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) instanceMethod send 


=\===\== <> >< instanceMethods sendWith 
class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


5.4.5.2. Comparison Methods 
>>-сошрагівоп орегазог(агришеп%)------------------------------- >< 


Returns 1 (true) or 0 (false), the result of performing the specified comparison operation. The receiver 
object and the argument are the terms compared. 


The comparison operators you can use in a message are: 


= True if the terms are equal 


ы, ><, <> True if the terms аге not equal (inverse of =) 
> Greater than 

< Less than 

>= Greater than or equal to 

\< Not less than 

<= Less than or equal to 

\> Not greater than 


All strict comparison operations have one of the characters doubled that define the operator. The 
Orderable strict comparison operators produce the same results as the non-strict comparisons. 


The strict comparison operators you can use in a message are: 


== True if terms are strictly equal 


\== True if the terms are NOT strictly equal (inverse of == 
>> Strictly greater than 

<< Strictly less than 

>>= Strictly greater than or equal to 

\<< Strictly NOT less than 

<<= Strictly less than or equal to 

\>> Strictly NOT greater than 
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5.4.6. The Comparator Class 


The Comparator class is the base class for implementing Comparator objects that can be used with the 
Array sortWith() or stableSortWith() method. The compare() method implements some form of 
comparison that determines the relative ordering of two objects. Many Comparator implementations are 
specific to particilar object types. 


Figure 5-33. The Comparator class and methods 
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Note: The Comparator class also has available class methods that its metaclass, the Class class, 
defines. 


This class is defined as a mixin class. 


5.4.6.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) “| instanceMethod send 


=\===\== <> >< instanceMethods sendWith 
class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


5.4.6.2. compare 


»»-compare(first,second)-------------------------------- >< 


" " 


This method returns if the second is larger than first object, "0" if the two objects are equal, and "1" 
second is smaller than first . 


The default Comparator compare() method assumes that first is an object that implements the 
Comparable compareTo() method. Subclasses may override this to implement more specific 
comparisons. 
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5.4.7. The CaselessComparator Class 


The CaselessComparator class performs caseless orderings of String objects. 


Figure 5-34. The CaselessComparator class and methods 
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Note: The CaselessComparator class also has available class methods that its metaclass, the Class 
class, defines. 


This class is defined as a mixin class. 
5.4.7.1. Inherited Methods 
Methods inherited from the Object class. 


new (class method) — instanceMethod send 
=\===\== <> >< instanceMethods sendWith 


class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


Methods inherited from the Comparator class. 


compare 


5.4.7.2. compare 


»»-compare(first,second)-------------------------------- >< 


" " 


This method returns if the second is larger than first object, "0" if the two objects are equal, and "1" 


second is smaller than first. The two strings are compared using a caseless comparison. 
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5.4.8. The ColumnComparator Class 


The CaselessColumnComparator class performs orderings based on specific substrings of String objects. 


Figure 5-35. The ColumnComparator class and methods 
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Note: The ColumnComparator class also has available class methods that its metaclass, the Class 
class, defines. 


This class is defined as a mixin class. 


5.4.8.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) instanceMethod send 


=\===\== <> >< instanceMethods sendWith 
class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


Methods inherited from the Comparator class. 


compare 


5.4.8.2. compare 


»»-compare(first,second)-------------------------------- >< 


" " 


This method returns if the second is larger than first object, "0" if the two objects are equal, and "1" 


second is smaller than first. Only the defined columns of the strings are compared. 
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5.4.8.3. init 
>>-init (start, length)---------------------------------- >< 


Initializes a comparator to sort strings starting at position start for length characters. 


5.4.9. The CaselessColumnComparator Class 


The CaselessColumnComparator class performs caseless orderings of specific substrings of String 
objects. 


Figure 5-36. The CaselessColumnComparator class and methods 
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Note: The CaselessColumnComparator class also has available class methods that its metaclass, 
the Class class, defines. 


This class is defined as a mixin class. 


5.4.9.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) instanceMethod send 
=\===\== <> >< instanceMethods sendWith 


class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


Methods inherited from the Comparator class. 
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compare 


5.4.9.2. compare 


»»-compare(first,second)-------------------------------- >< 


This method returns "-1" if the second is larger than first object, "0" if the two objects are equal, and "1" 
second is smaller than first. Only the defined columns of the strings are compared, using a caseless 
comparison. 


5.4.9.3. init 
>>-init (start, length)---------------------------------- >< 


Initializes a comparator to sort strings starting at position start for length characters. 


5.4.10. The DescendingComparator Class 


The DescendingComparator class performs sort orderings in descending order. This is the inverse of a 
Comparator sort order. 


This class is defined as a mixin class. It must be used by inheriting from it as a mixin. 


Figure 5-37. The DescendingComparator class and methods 
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Note: The DescendingComparator class also has available class methods that its metaclass, the 
Class class, defines. 


This class is defined as a mixin class. 
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5.4.10.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) instanceMethod send 
=\===\== <> >< instanceMethods sendWith 


class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


Methods inherited from the Comparator class. 


compare 


5.4.10.2. compare 


»»-compare(first,second)-------------------------------- >< 


This method returns "1" if the second is larger than first object, "0" if the two objects are equal, and "-1" 
second is smaller than first, resulting in a descending sort sequence. The DescendingComparator 
assumes the first object implements the Comparable compareTo() method. 


5.4.11. The CaselessDescendingComparator Class 


The CaselessDescendingComparator class performs caseless string sort orderings in descending order. 
This is the inverse of a CaselessComparator sort order. 
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Figure 5-38. The CaselessDescendingComparator class and methods 
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Note: The CaselessDescendingComparator class also has available class methods that its 


metaclass, the Class class, defines. 


This class is defined as a mixin class. 


5.4.11.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method)  instanceMethod 


=\===\== <> >< instanceMethods 
class isA 

copy isInstanceOf 
defaultName objectName 
hasMethod objectName= 
identityHash Request 

init Run 


send 

send With 
setMethod 
Start 


startWith 
string 
unsetMethod 


Methods inherited from the Comparator class. 


compare 


5.4.11.2. compare 


»»-compare(first,second)------------ 


This method returns "1" if the second is larger than first object, "0" if the two objects are equal, and "-1" 
second is smaller than first. The two strings are compared using a caseless comparison. 


5.4.12. The InvertingComparator Class 


The InvertingComparator class inverts the comparison results of another Comparator object to reverse 


the resulting sort order. 
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Figure 5-39. The InvertingComparator class and methods 
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Note: The InvertingComparator class also has available class methods that its metaclass, the Class 
class, defines. 


This class is defined as a mixin class. 
5.4.12.1. Inherited Methods 
Methods inherited from the Object class. 


new (class method) instanceMethod send 
=\= ==\== <> >< instanceMethods sendWith 


class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


Methods inherited from the Comparator class. 


compare 


5.4.12.2. compare 


»»-compare(first,second)-------------------------------- >< 


This method returns "1" if the second is larger than first object, "0" if the two objects are equal, and "-1" 
second is smaller than first, resulting in a descending sort sequence. The InvertingComparator will invert 
the ordering returned by the provided Comparator. 
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5.4.12.3. init 


»»-init(comparator)---------------------------------- >< 


Initializes an inverting comparator to sort strings using an inversion of the result from the comparator 
compare() method. 


5.4.13. The Monitor Class 


The Monitor class acts as a proxy for other objects. Messages sent to the Monitor object are forwarded to 
a different target object. The message target can be changed dynamically. 


Figure 5-40. The Monitor class and methods 
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Note: The Monitor class also has available class methods that its metaclass, the Class class, 
defines. 


5.4.13.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) instanceMethod send 
=\===\== <> >< instanceMethods sendWith 


class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 
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5.4.13.2. current 
22 7 CUTTe Nt ae a ee a Se Sa ee eo eee ae >< 


Returns the current destination object. 


5.4.13.3. destination 


22-destination--b------—-—------— HSS SSS SSS SSS aaa eS SS Sasa Ss >< 
+-(destination) -+ 


Returns a new destination object. If you specify destination, this becomes the new destination for any 
forwarded messages. If you omit destination, the previous destination object becomes the new 
destination for any forwarded messages. 


5.4.13.4. init 


>>-init--+--------------- %------------------------------------- >< 


*-(destination)--* 


Initializes the newly created monitor object. 


5.4.13.5. unknown 


»»-unknown(messagename,messageargs)---------------------------- >< 


Reissues or forwards to the current monitor destination all unknown messages sent to a monitor object. 
For additional information, see Defining an unknown Method. 


5.4.13.6. Examples 


.local~setentry("output", .monitor~new(.stream~new("my.new")~~command("open nobuffer"))) 


/* The following sets the destination */ 

previous destination-.output^destination(.stream^new("my.out")^^command("open write")) 
/* The following resets the destination */ 

.output^destination 


.output^destination(.Stdout) 
current, output destination stream object-.output^current 


5.4.14. The MutableBuffer Class 


The MutableBuffer class is a buffer on which certain string operations such as concatenation can be 
performed very efficiently. Unlike String objects, MutableBuffers can be altered without requiring a new 
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object allocation. A MutableBuffer object can provide better performance for algorithms that involve 
frequent concatenations to build up longer string objects because it creates fewer intermediate objects. 


Figure 5-41. The MutableBuffer class and methods 





MutableBuffer 








matchChar 

















append overlay 
caselessChangeStr pos 
caselessCountStr replaceAt 
caselessLastPos subChar 
caselessMatch subStr 
caselessMatchChar subWord 
caselessPos translate 
cadelessW ordPos upper 
changestr verify 
countstr word 
delete wordindex 
delWord wordLength 
getBufferSize wordPos 
insert words 
lastPos 

length 

lower 

makeArray 

match 





Note: The MutableBuffer class also has available class methods that its metaclass, the Class class, 


defines. 
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5.4.14.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) — instanceMethod send 
=\===\== <> >< instanceMethods sendWith 


class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


5.4.14.2. new 


»»-new(-4-------- T---------------- %-)-------------------- >< 
+-string-+ +-,-buffersize--+ 


Initialize the buffer, optionally assign a buffer content and a starting buffer size. The default size is 256; 
the buffer size increases to the length of string if the string does not fit into the buffer. 


5.4.14.3. append 


»»-append(string)------------------------------------------ >< 


Appends string to the buffer content. The buffer size is increased if necessary. 


5.4.14.4. caselessChangeStr 


>>-caselessChangeStr (needle,newneedle--4-------- %--)--------------------------------- >< 
+-,count-+ 


Returns the receiver MutableBuffer newneedle replacing occurrences of needle. If count is not specified, 
all occurrences of needle are replaced. If count is specified, it must be a positive, whole number that 
gives the maximum number of occurrences to be replaced. The needle searches are performed using 
caseless comparisons. 


5.4.14.5. caselessCountStr 


>>-caselessCountStr (needle)-------------------------------------------- >< 


Returns a count of the occurrences of needle in the receiving MutableBuffer that do not overlap. АП 
matches are made using caseless comparisons. 


5.4.14.6. caselessLastPos 


>>-caselessLastPos (needle-4--------------------------- %-)--->< 
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%-,--%------- +--+--------- +-+ 
+-start-+ +-,length-+ 


Returns the position of the last occurrence of a string, needle, in the receiving buffer. (See also POS.) It 
returns 0 if needle is the null string or not found. By default, the search starts at the last character of the 
receiving buffer and scans backward to the beginning of the string. You can override this by specifying 
start, the point at which the backward scan starts and length, the range of characters to scan. The start 
must be a positive whole number and defaults to receiving buffer^length if larger than that value or 
omitted. The length must be a non-negative whole number and defaults to start. The search is performed 
using caseless comparisons. 


5.4.14.7. caselessMatch 


»»-caselessMatch(start,other-4---------------------------- %-)------------------- >< 
%-,--%---%--%---------4-% 
%-п-% +-,length-+ 


Returns .true ("1") if the characters of the other match the characters of the target buffer beginning at 
position start. Return .false ("0") if the characters are not a match. The matching is performed using 
caseless comparisons. start must be a positive whole number less than or equal to the length of the target 
buffer. 


If n is specified, the match will be performed starting with character n of other. The default value for n is 
"1". n must be a positive whole number less than or equal to the length of other. 


If length is specified, it defines a substring of other that is used for the match. length must be a positive 
whole number and the combination of n and length must be a valid substring within the bounds of other. 


The caselessMatch method is useful for efficient string parsing as it does not require new string objects 
be extracted from the target string. 


5.4.14.8. caselessMatchChar 


>>-caselessMatchChar (n,chars)------------------------- >< 


Returns .true ("1") if the character at position n matches any character of the string chars. Returns .false 
("0") if the character does not match any of the characters in the reference set. The match is made using 
caseless comparisons. The argument n must be a positive whole number less than or equal to the length 
of the target MutableBuffer. 


5.4.14.9. caselessPos 


>>-caselessPos (needle-4--------------------------- %-)--->< 
%-,--%------- %--%--------- +-+ 
+-start-+ +-,length-+ 


Returns the position in the receiving buffer of a needle string. (See also caselessLastPos.) It returns 0 if 
needle is the null string or is not found or if start is greater than the length of the receiving buffer. The 
search is performed using caseless comparisons. By default, the search starts at the first character of the 
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receiving buffer (that is, the value of start is 1), and continues to the end of the buffer. You can override 
this by specifying start, the point at which the search starts, and length, the bounding limit for the search. 
If specified, start must be a positive whole number and length must be a non-negative whole number. 


5.4.14.10. caselessWordPos 


»»-caselessWordPos(phrase-4-------- %-)--------------------------------- >< 
+-,start-+ 


Returns the word number of the first word of phrase found in the receiving buffer, or 0 if phrase contains 
no words or if phrase is not found. Word matches are made independent of case. Multiple whitespace 
characters between words in either phrase or the receiving buffer are treated as a single blank for the 
comparison, but, otherwise, the words must match exactly. 


By default the search starts at the first word in the receiving string. You can override this by specifying 
start (which must be positive), the word at which the search is to be started. 


5.4.14.11. changeStr 


>>-changeStr (needle ,newneedle--+-------- +-е-----------4------------<------ >< 


Returns Ше receiver MutableBuffer with newneedle replacing occurrences of needle. 


If count is not specified, all occurrences of needle are replaced. If count is specified, it must be a positive, 
whole number that gives the maximum number of occurrences to be replaced. 


5.4.14.12. countStr 
»»-count$Str(needle)-------------------------------------------- >< 


Returns a count of the occurrences of needle in the receiving buffer that do not overlap. 


5.4.14.13. delete 


»»-delete(n---4--------- %--)------------------------------- >< 
+-,length-+ 


Deletes length characters from the buffer beginning at the n’th character. If length is omitted, or if length 
is greater than the number of characters from n to the end of the buffer, the method deletes the remaining 
buffer contents (including the n’th character). The length must be a positive integer or zero. The » must 
be a positive integer. If n is greater than the length of the buffer or zero, the method does not modify the 
buffer content. 
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5.4.14.14. delstr 


>>-delstr (n---+--------- %--)------------------------------- >< 
+-,length-+ 


Deletes length characters from the buffer beginning at the n’th character. If length is omitted, or if length 
is greater than the number of characters from n to the end of the buffer, the method deletes the remaining 
buffer contents (including the n’th character). The length must be a positive integer ог zero. The и must 
be a positive integer. If n is greater than the length of the buffer or zero, the method does not modify the 
buffer content. The delstr() method is the same as the delete() method. It is provided for polymorphism 
with the String class. 


5.4.14.15. delWord 


»»-delWord(n--4--------- %--)----------------------------------- >< 
+-,length-+ 


Deletes a substring from the MutableBuffer the substring that starts at the nth word and is of length 
whitespace-delimited words. If you omit length, or if length is greater than the number of words from n 
to the end of the receiving bufffer, the method deletes the remaining words in the receiving buffer 
(including the nth word). The length must be a positive whole number or zero. The n must be a positive 
whole number. If и is greater than the number of words in the receiving buffer, the method returns the 
receiving buffer unchanged. The portion deleted includes any whitespace characters following the final 
word involved but none of the whitespace characters preceding the first word involved. 


5.4.14.16. getBufferSize 
>>-ребВшіТек512е------------<-----------------------------. >< 


Retrieves the current buffer size. 


5.4.14.17. insert 


»»-insert (new-4----------------------------------------- %--)>< 


+-length-+ +-,pad-+ 


Inserts the string new, padded or truncated to length length, into the mutable buffer after the n’th 
character. The default value for n is 0, which means insertion at the beginning of the string. If specified, n 
and length must be positive integers or zeros. If n is greater than the length of the buffer contents, the 
string new is padded at the beginning. The default value for length is the length of new. If length is less 
than the length of string new, insert truncates new to length length. The default pad character is a blank. 


ooRexx Reference Version 4.0.0 333 


Chapter 5. The Builtin Classes 


5.4.14.18. lastPos 


>>-lastPos (пеедїе-+-------- %-)--------------------------------- >< 
+-,start-+ 


Returns the position of the last occurrence of a string, needle, in the receiving buffer. (See also POS.) It 
returns 0 if needle is the null string or not found. By default, the search starts at the last character of the 
receiving buffer and scans backward. You can override this by specifying start, the point at which the 
backward scan starts. The start must be a positive whole number and defaults to 

receiving buffer^length if larger than that value or omitted. 


Examples: 


хі - .mutablebuffer^new("abc def ghi") 
xi^lastPos(" ") -> 8 

хі - .mutablebuffer^new("abcdefghi") 
xi^lastPos(" ") -> 0 

xi - .mutablebuffer^new("efgxyz") 
х171ав%Ров("ху") -> 4 

хі - .mutablebuffer^new("abc def ghi") 
xi^lastPos(" ",7) -> 4 


5.4.14.19. length 


>2-Тепрън-------нн << <---ннняя- 9 9н----- ня -- вен >< 


Returns length of data in buffer. 


5.4.14.20. lower 


>>-lower (+---+--+--------- %---)---------------------- >< 
%-п-% +-,length-+ 


Returns the receiving buffer with the characters of the target string beginning with character n for length 
characters converted to lowercase. If n is specified, it must be a positive whole number. If n is not 
specified, the case conversion will start with the first character. If length is specified, it must be a 
non-negative whole number. If length the default is to convert the remainder of the buffer. 


5.4.14.21. makeArray 


»»-makeArray(-4----------- %-)---->< 
+-Separator-+ 


This method returns an array of strings containing the substrings that were separated using the separator 
character. The default separator is the newline character. 
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5.4.14.22. match 


»»-match(start,other-4---------------------------- %-)------------------- >< 
%-,--%---4--%---------4-% 
%-п-% +-,length-+ 


Returns .true ("1") if the characters of the other match the characters of the target buffer beginning at 
position start. Return .false ("0") if the characters are not a match. start must be a positive whole number 
less than or equal to the length of the target buffer. 


If n is specified, the match will be performed starting with character n of other. The default value for n is 
"1". n must be a positive whole number less than or equal to the length of other. 


If length is specified, it defines a substring of other that is used for the match. length must be a positive 
whole number and the combination of n and length must be a valid substring within the bounds of other. 


The match method is useful for efficient string parsing as it does not require new string objects be 
extracted from the target buffer. 


5.4.14.23. matchChar 


>>-matchChar (n,chars)------------------------- >< 


Returns .true ("1") if the character at position n matches any character of the string chars. Returns .false 
("0") if the character does not match any of the characters in the reference set. The argument n must be a 
positive whole number less than or equal to the length of the target buffer. 


5.4.14.24. overlay 


»»-overlay (new-*----------------------------------------- %--)-->< 
%-,--%---%--%-------------------------- +--+ 


И 


%-п-% +-,--+-------- +--+------ +--+ 
+-length-+ +-,рад-+ 


Modifies Ше buffer content by overlaying it, starting at the n’th character, with the string new, padded or 
truncated to length length. The overlay can extend beyond the end of the buffer. In this case the buffer 
size will be increased. If you specify length, it must be a positive integer or zero. The default value for 
length is the length of new. If n is greater than the length of the buffer content, padding is added before 
the new string. The default pad character is a blank, and the default value for n is 1. If you specify n, it 
must be a positive integer. 


5.4.14.25. pos 


>>-pos (needle-4-------- %-)------------------------------------- >< 
+-,start-+ 


Returns the position in the receiving buffer of another string, needle. (See also lastPos.) It returns 0 if 
needle is the null string or is not found or if start is greater than the length of the receiving buffer. By 
default, the search starts at the first character of the receiving buffer (that is, the value of start is 1). You 
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can override this by specifying start (which must be a positive whole number), the point at which the 
search starts. 


Examples: 


хі = .mutablebuffer^new("Saturday") 


x1~pos ("day") -> 6 
x1 = .mutablebuffer^new("abc def ghi") 
x1l^pos("x") -> 0 
x1~pos(" ") -> 4 
x1~pos(" ",5) -> 8 


5.4.14.26. replaceAt 


>>-replaceAt (new,n, length-+------ +-)----- >< 
+-,pad-+ 


Returns the receiving buffer with the characters from the nth character for length characters replaced 
with new. The replacement position and length can extend beyond the end of the receiving string. The 
starting position, n, must be a positive whole number, and the length must be a positive whole number or 
Zero. If n is greater than the length of the receiving string, padding is added before the new string. The 
default pad character is a blank. 


5.4.14.27. setBufferSize 


»»-setBufferSize(n)---------------------------------------- >< 


Sets the buffer size. If n is less than the length of buffer content, the content is truncated. If n is 0, the 
entire contents is erased and the new buffer size is the value given in the init method. 


5.4.14.28. string 


>>-въпиро------+<-----#------<<<+++++----+<--- << >< 


Retrieves Ше content of the buffer as a string. 


5.4.14.29. subchar 


»»-subchar(n)---------------------------------------------- >< 


Returns the n’th character of the receiving buffer. n must be a positive whole number. If n is greater that 
the length of the receiving buffer then a zero-length string is returned. 
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5.4.14.30. substr 


»»-substr(n-4-------------------------- p--)o2esezBc-2sesc-k >< 
%-,--%-------- %--%------ +--+ 


*t-length-* +-,pad-+ 


Returns a substring from the buffer content that begins at the n’th character and is of length length, 
padded with pad if necessary. The n must be a positive integer. If n is greater than 

receiving string-length, only pad characters are returned. If you omit length, the remaining buffer 
content is returned. The default pad character is a blank. 


5.4.14.31. subWord 


»»-subWord(n-4--------- %-)--------------------з-с-------------- >< 
+-,length-+ 


Returns the substring of the receiving buffer that starts at the nth word and is up to length 
whitespace-delimited words. The n must be a positive whole number. If you omit length, it defaults to the 
number of remaining words in the receiving buffer. The returned string never has leading or trailing 
whitespace characters, but includes all whitespace characters between the selected words. 


5.4.14.32. translate 


>>2-Ъгапвтаре-+#--стллт-в тента нета таланта тата патента тататита тт тате += 
>< 
%-(---------------------------------------- %-%----------------------- +-)-+ 
+-tableo--+------------------------- +-+ +-,--+---+--+---------+-+ 
+- --+--------+--+------+-+ +-n-+ +-,length-+ 
+-tablei-+ +-,pad-+ 


Returns the receiving buffer with each character translated to another character or unchanged. 


The output table is tableo and the input translation table is tablei. translate searches tablei for each 
character in the receiving buffer. If the character is found, the corresponding character in tableo is 
replaces the character in the buffer. If there are duplicates in tablei, the first (leftmost) occurrence is used. 
If the character is not found, the original character in the receiving buffer is unchanged. 


The tables can be of any length. If you specify neither translation table and omit pad, the receiving string 
is translated to uppercase (that is, lowercase a-z to uppercase A-Z), but if you include pad the buffer 
translates the entire string to pad characters. tablei defaults to XRANGE("00"x , "FF"x), and tableo defaults 
to the null string and is padded with pad or truncated as necessary. The default pad is a blank. 


n is the position of the first character of the translated range. The default starting position is 1. length is 
the range of characters to be translated. If omitted, length remainder of the buffer from the starting 
position to the end is used. 


5.4.14.33. upper 


»»-upper(4---4--4--------- %---)---------------------- >< 
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%-п-% +-,length-+ 


Returns the receiving buffer with the characters of the target string beginning with character n for length 
characters converted to uppercase. If n is specified, it must be a positive whole number. If n is not 
specified, the case conversion will start with the first character. If length is specified, it must be a 
non-negative whole number. If length the default is to convert the remainder of the buffer. 


5.4.14.34. verify 


»»-verify (reference-4---------------------------------------------- %-)-->< 
%-,--%-------- %--%--------------------------- +-+ 


И 


+=Option=t 4£-,--4-————-—— +--+--------- +-+ 
*-start-* +-,length-+ 


Returns a number that, by default, indicates whether the receiving buffer is composed only of characters 
from reference. It returns 0 if all characters in the receiving buffer are in reference or returns the position 
of the first character in the receiving buffer not in reference. 


The option can be either Nomatch (the default) or Match. (You need to specify only the first capitalized 
and highlighted letter; all characters following the first character are ignored, which can be in uppercase 
or lowercase.) 


If you specify Match, the method returns the position of the first character in the receiving buffer that is in 
reference, or returns 0 if none of the characters are found. 


The default for start is 1. Thus, the search starts at the first character of the receiving buffer. You can 
override this by specifying a different start point, which must be a positive whole number. 


The default for length is the length of the buffer from start to the end of the buffer. Thus, the search 
proceeds to the end of the receiving buffer. You can override this by specifying a different length, which 
must be a non-negative whole number. 


If the receiving string is null, the method returns 0, regardless of the value of the option. Similarly, if 
start is greater than receiving buffer^length, the method returns 0. If reference is null, the method 
returns 0 if you specify Match. Otherwise, the method returns the start value. 


Examples: 

.mutablebuffer^new(?123?)^verify (1234567890?) -» 0 
-mutablebuffer~new(’1Z3’) “verify (1234567890?) -> 2 
.mutablebuffer^new(? AB4T’ )~verify(’ 1234567890?) -» 1 
.mutablebuffer^new(? ABAT?)^verify (2? 1234567890? ,? M?) -» 3 
.mutablebuffer^new(? ABAT?)^verify (1234567890? ,’N’) -» 1 
.mutablebuffer^new(? 1P3Q4?)^verify (1234567890? , ,3) -> 4 
.mutablebuffer^new(?123?)^verify("",N,2) -» 2 
.mutablebuffer^new(' ABCDE?)^verify("", ,3) -> 3 
.mutablebuffer^new(? AB3CD5?)^verify (1234567890? ,’M’ ,4) -> 6 
.mutablebuffer^new(? ABCDEF’ ) ^verify C ABC’ ,"N",2,3) -> 4 
.mutablebuffer^new(? ABCDEF?)^verify C ADEF? ,"M",2,3) -> 4 
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5.4.14.35. word 
»»-word(n)----------------------------------------------------- >< 


Returns the nth whitespace-delimited word in the receiving buffer or the null string if the receiving buffer 
has fewer than n words. The n must be a positive whole number. This method is exactly equivalent to 


receiving buffer^subWord(n,1). 


5.4.14.36. wordlndex 


»»-wordIndex(n)------------------------------------------------ >< 


Returns the position of the first character in the nth whitespace-delimited word in the receiving buffer. It 
returns 0 if the receiving buffer has fewer than n words. The n must be a positive whole number. 


5.4.14.37. wordLength 


»»-wordLength(n)----------------------------------------------- >< 


Returns the length of the nth whitespace-delimited word in the receiving buffer or 0 if the receiving 
buffer has fewer than n words. The n must be a positive whole number. 


5.4.14.38. wordPos 


»»-wordPos(phrase-4-------- Е ааста aaa a я----< >< 
+-,start-+ 


Returns the word number of the first word of phrase found in the receiving buffer, or 0 if phrase contains 
no words or if phrase is not found. Multiple whitespace characters between words in either phrase or the 
receiving buffer are treated as a single blank for the comparison, but, otherwise, the words must match 
exactly. 


By default the search starts at the first word in the receiving buffer. You can override this by specifying 
start (which must be positive), the word at which the search is to be started. 


5.4.14.39. words 


>2-ипогав---------------- аа ааа >< 


Returns the number of whitespace-delimited words іп the receiving buffer. 


5.4.15. The RegularExpression Class 


This class provides support for regular expressions. A regular expression is a pattern you can use to 
match strings. 
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Note: The RegularExpression class is not a built-in class and is NOT preloaded. It is defined in the 
rxregexp.cls file. This means you must use а ::requires statement to activate its functionality, as 
follows: 


: :геди1гез "rxregexp.cls" 


Figure 5-42. The RegularExpression class and methods 





RegularExpression 


“requires rxregexp.cls 


Init 
match 
parse 
pos 
position 





Note: The RegularExpression class also has available class methods that its metaclass, the Class 
class, defines. 


Here is a description of the syntax: 


| OR operator between Ше left and right expression 


? Matches any single character 

T Matches the previous expression zero or more times 
+ Matches the previous expression one or more times 
\ "Escape" symbol: use the next character literally 

0 Expression in parenthesis (use where needed) 

{n} Matches previous expression n times (n>1) 
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Set definition: matches any single character out of the defined set. 
А '^ right after the opening bracket means that none of the following characters 
should be matched. 


А - (if not used with 'V) defines a range between the last specified character and 


' 


the one following '-'. If it is the first character in the set definition, it is used 


literally. 


The following symbolic names (they must start and end with ':') can be used to abbreviate common sets: 


: ALPHA: 
:LOWER: 
‘UPPER: 
:DIGIT: 
:ALNUM: 
:XDIGIT: 
:BLANK: 
:SPACE: 
:CNTRL: 
: PRINT: 
:ОКАРН: 
:PUNCT: 


Examples: 


Characters in the range A-Z and a-z 
Characters in the range a-z 

Characters in the range A-Z 
Characters in the range 0-9 

Characters in :DIGIT: and :ALPHA: 
Characters in :DIGIT:, A-F and a-f 
Space and tab characters 

Characters "09"x to "0D"x and space 
Characters "00"x to "1F"x and "7Е"х 
Characters in the range "20"x to "7E"x 
Characters in :PRINT: without space 
All :PRINT: characters without space and not in :ALNUM: 


: :геди1гез "rxregexp.cls" 


"(HilHello) World" Matches "Hi World" and 


"Е11е.???" 


"file.?{3}" 
"a жы" 


"a +b" 


"file.[bd]at" 


"Hello World". 

Matches any file with three 
characters after "." 

Same as above. 

Matches all strings that begin with 
"a" and end with "b" and have an 
arbitrary number of spaces in between 
both. 

Same as above, but at least one space 
must be present. 

Matches "file.bat" and "file.dat". 


"[A-Za-z]*" Matches any string containing only 
letters. 

"[: ALPHA: | +" Same as above, using symbolic names. 

"Г“0-91ж" Matches any string containing по 
numbers, including the empty string. 

"({:DIGIT: : LOWER: ]" A single character, either a digit or 
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"This is (very )*nice." Matches all strings with one or more 
occurrences of "very " between 
"This is " and "nice.". 


5.4.15.1. Inherited Methods 
Methods inherited from the Object class. 


new (class method) — instanceMethod send 
=\===\== <> >< instanceMethods sendWith 


class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


5.4.15.2. init 


+-,-"MAXIMAL"--+ 
»»-init(-4--------- %-%-------------- %-)-------------------- >< 
+-Pattern-+ +-,-"MINIMAL"--+ 


Instantiates a RegularExpression object. Use the optional parameter Pattern to define a pattern that is 
used to match strings. See the introductory text below for a description of the syntax. If the strings 
match, you can decide whether you want to apply "greedy" matching (a maximum-length match) or 
"non-greedy" matching (a minimum-length match). 


Examples: 


myRE1 
myRE2 


.RegularExpression^new 


.RegularExpression^new("Hello?*") 


5.4.15.3. match 


»»-match(-string-)----------------------------------------- >< 


This method tries to match string to the regular expression that was defined on the "new" invocation or 
on the "parse" invocation. It returns 0 on an unsuccessful match and | on a successful match. For an 
example see Parse. 


5.4.15.4. parse 


+-,-"CURRENT"--+ 
»»-parse(-Pattern-4-------------- %------------------------- >< 
+-,-"MAXIMAL"--+ 
+-,-"MINIMAL"--+ 
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This method creates the matcher used to match a string from the regular expression specified with 
Pattern. The RegularExpression object uses this regular expression until a new invocation of Parse takes 
place. The second (optional) parameter specifies whether to use minimal or maximal matching. The 
default is to use the current matching behavior. 


Return values: 


0 

Regular expression was parsed successfully. 
1 

An unexpected symbol was met during parsing. 
2 

A missing ')' was found. 
3 

An illegal set was defined. 
4 

The regular expression ended unexpectedly. 
5 


An illegal number was specified. 


Example 1: 


a.0 = "does not match regular expression" 

a.1 - "matches regular expression" 

b = .array~of("This is a nice flower.", 
"This is a yellow flower.", 
"This is a blue flower.", 
"Hi there!") 

myRE = .RegularExpression^ new 


e = myRE^parse("This is a ???? flower.") 
if e == 0 then do 
do i over b 
j = nyRE^match(i) 
say i~left(24) ">>" а.) 
end 
end 
else 
say "Error" e "occurred!" 
exit 


: :геди1гез "rxregexp.cls" 


Output: 


ooRexx Reference Version 4.0.0 343 


Chapter 5. The Builtin Classes 


This is a nice flower. >> Does match regular expression 
This is a yellow flower. >> Does not match regular expression 
This is a blue flower. >> Does match regular expression 

Hi there! >> Does not match regular expression 
Example 2: 

a.0 = "an invalid number!" 

a.1 - "a valid number." 

b=. array^of ("1" , "42" я non Қ "5436412" , "а" А "f43g") 


myRE = .RegularExpression^new(" [1-9] [0-9]*") 
do i over b 
j = nyRE^match(i) 
say i "is" a.j 
end 
say 


/* Now allow "hex" numbers and a single 0 */ 
if myRE^parse("O|([1-9a-f][0-9a-f]*)") == 0 then до 
do i over b 
j = myRE~match(i) 
say i "is" a.j 
end 
end 
else 
say "invalid regular expression!" 


exit 

: :геди1гез "rxregexp.cls" 

Example 3: 

str = "<p>Paragraph 1</p><p>Paragraph 2</p>" 

myRE1 = .RegularExpression~new("<p>?*</p>", "MINIMAL" ) 
myRE1~match(str) 

myRE2 = .RegularExpression~new("<p>?*</p>", MAXIMAL") 


myRE2~match(str) 


say "myRE1 (minimal) matched" str~substr(1,myRE1~position) 
say "myRE2 (maximal) matched" str^substr(1,myRE2^position) 


::requires "rxregexp.cls" 
Output: 


myRE1 (minimal) matched <p>Paragraph 1</p> 
myRE2 (maximal) matched <p>Paragraph 1</p><p>Paragraph 2</p> 
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5.4.15.5. pos 
»»-pos-(-haystack-)---------------------------------------- >< 


This method tries to locate а string defined by the regular expression on the "new" invocation or on the 
"parse" invocation in the given haystack string. It returns 0 on an unsuccessful match or the starting 
position on a successful match. The end position of the match can be retrieved with the position method. 


Example: 

Str - "It is the year 2002!" 

myRE = .RegularExpression^new("[1-9] [0-9] *") 

begin = myRE^pos(str) 

if begin > 0 then do 
year = str^substr(begin, myRE^position - begin + 1) 
say "Found the number" year "in this sentence." 

end 


::requires "rxregexp.cls" 
Output: 


Found the number 2002 in this sentence. 


5.4.15.6. position 


>2-ровъноп------------- ан cei >< 


Returns the character position at which the last parse(), pos(), or match() method ended. 


Example: 

myRE = .RegularExpression^new 

myRE~ parse ("[abc") -- illegal set definition 
say myRE^ position -- will be 4 


myRE = .RegularExpression~new("[abc]12") 
myRE^match("ci2") 
say myRE^ position -- will be 3 


myRE^match("a13") 
say myRE^position -- will be 2 (failure to match) 


::requires "rxregexp.cls" 


5.4.16. The RexxQueue Class 


The RexxQueue class provides object-style access to Rexx external data queues. 
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Figure 5-43. The RexxQueue class and methods 
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Note: The RexxQueue class also has available class methods that its metaclass, the Class class, 


defines. 


5.4.16.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) 
mecum 


class 


copy 
defaultName 


hasMethod 
identityHash 
init 


instanceMethod 
instanceMethods 


isA 
isInstanceOf 
objectName 
objectName= 
Request 

Run 


send 
sendWith 
setMethod 
Start 


startWith 
string 
unsetMethod 
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5.4.16.2. create (Class Method) 
»»-create(name)-------------------------------------------- >< 


Attempts to create an external Rexx named queue using name. If a name queue already exists, а new 
queue with a Rexx-generated name will be created. This method returns the name of the created queue, 
which will be either name, or a generated name if there is a conflict. 


5.4.16.3. delete (Class Method) 


»»-delete(name)-------------------------------------------- >< 


Attempts to delete an external Rexx named queue named name. This method returns "0" if the queue was 
successfully deleted. Non-zero results are the error codes from the RexxDeleteQueue() programming 
interface. 


5.4.16.4. exists (Class Method) 


>>-exists (name)-------------------------------------------- >< 


Tests if an external Rexx queue name currently exists, returning | (true) if it does and 0 (false) otherwise. 


5.4.16.5. open (Class Method) 


»»-open(name)-------------------------------------------- >< 


Tests if the external Rexx named queue nameexists and creates the queue if it does not. 


5.4.16.6. delete 


>>-детерв-------- е asta eae san SSCS SSeS RSS CREE >< 


Deletes the Rexx external queue associated with this RexxQueue instance. 


5.4.16.7. empty 


>2-ешръу------< a a a a a a a Т >< 


Removes all items from the Rexx external queue associated with this RexxQueue instance. 


5.4.16.8. get 


Returns the name of the Rexx external queue associated with this instance. 
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5.4.16.9. init 


»»-init(-4------ ha) Seas aoa sSeaSosan Sane aaa aseeeas—= >< 


+-паше-+ 


Initializes а new RexxQueue instance associated with the named Rexx external queue. If name is not 
specified, the SESSION queue is used. If the named queue does not exist, one will be created. 


5.4.16.10. lineln 


eer ine inne ssa sae Se Se eS Банан анын >< 


Reads a single line from the Rexx external queue. If the queue is empty, lineIn will wait until a line is 
added to the queue. 


5.4.16.11. lineOut 


»»-lineOut(-4------ %-)---------------------------------- >< 
+-line-+ 


Adds a line to the Rexx external queue in first-in-first-out (FIFO) order. If line is not specified, a null 
string ("") is added. 


5.4.16.12. makeArray 


>2-шакейттау------ vocc RS SSSR Se SS SaaS a >< 


Returns a single-index array with the same number of items as the receiver object. Items in the new array 
will have the same order as the items in the external queue. The external queue is emptied. 


5.4.16.13. pull 


>> 0 aaa oe >< 


Reads a line from the Rexx external queue. If the queue is currently empty, this method will immediately 
return the Nil Object without waiting for lines to be added to the queue. 


5.4.16.14. push 


»»-push(-4------ %-)---------------------------------- >< 
+-1іпе-+ 


Adds a line to ће Rexx external queue in last-in-last-out (LIFO) order. If line is not specified, a null 
string ("") is added. 
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5.4.16.15. queue 


»»-queue(-4------ %-)---------------------------------- >< 
+-1іпе-+ 


Adds a line to ће Rexx external queue in first-in-first-out (FIFO) order. If line is not specified, a null 
string ("") is added. 


5.4.16.16. queued 


>>-дшешей-<-----ытел- ае ae Saas Se aS SSeS ee asa a >< 


Returns the count of lines currently in the Rexx external queue. 


5.4.16.17. say 


>>-вау(-+------ %-)---------------------------------- >< 
+-1іпе-+ 


Adds a line to ће Rexx external queue in first-in-first-out (FIFO) order. If line is not specified, a null 
string ("") is added. 


5.4.16.18. set 


>>-set (name)---------------------------------- >< 


Switches the Rexx external queue associated with the RexxQueue instance. The new queue must have 
been previously created. The method return value is the name of current queue being used by the 
instance. 


5.4.17. The Supplier Class 


You can use a supplier object to iterate over items of a collection. Supplier objects are created from a 
snapshot of a collection. The iteration results are not affected by later changes to the source collection 
object. 
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Figure 5-44, The Supplier class and methods 


Supplier 


new 





alllndexes 
allltems 
available 
getArrays 
index 

init 

items 

next 
supplier 





Note: The Supplier class also has available class methods that its metaclass, the Class class, 
defines. 


5.4.17.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) instanceMethod send 


= \= == \== <> >< instanceMethods sendWith 
class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


5.4.17.2. new (Class Method) 


»»-new(items,indexes)----------------------------------------- >< 


Returns a new supplier object. The items argument must be an array of objects over which the supplier 
iterates. The indexes argument is an array of index values with a one-to-one correspondence to the 
objects contained in the items array. The created supplier iterates over the arrays, returning elements of 
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the values array in response to items messages, and elements of the indexes array in response to index 


messages. The supplier iterates for the number of items contained in the values array, returning the Nil 
object for any nonexistent items in either array. 


5.4.17.3. alllndexes 


?22-аШешв----- 7 ---#--93--+-#-+--++---+<+-++#+++- нане >< 


Returns an array of all index values from Ше current supplier position to Ше end of the supplier. Once 
allIndexes is called, no additional items can be retrieved from the supplier. Calls to available will return 
"0" (false). 


5.4.17.4. allltems 


22-ай1Прешв----- пяна ат C EUM ULIS ee ce >< 


Returns an array of all items from the current supplier position to the end of the supplier. Once allItems 
is called, no additional items can be retrieved from the supplier. Calls to available will return "0" (false). 


5.4.17.5. available 


>>- available --- ee >< 


Returns 1 (true) if an item is available from Ше supplier (that is, if the item method would return a value). 
It returns 0 (false) if the collection is empty or the supplier has already enumerated the entire collection. 


5.4.17.6. index 


Returns the index of the current item in the collection. If no item is available, that is, if available would 
return false, the supplier raises an error. 


5.4.17.7. init 


Initializes the object instance. 


5.4.17.8. item 


>>-преш------------+--+----++<-----<--<-+<+----<-+-<<+---- ---#--<+------<<< >< 
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Returns the current item in the collection. If no item is available, that is, if available would return false, 
the supplier raises an error. 


5.4.17.9. next 


2 mher ns >< 


Moves to the next item in the collection. By repeatedly sending next to the supplier (as long as available 
returns true), you can enumerate all items in the collection. If no item is available, that is, if available 
would return false, the supplier raises an error. 


5.4.17.10. Examples 


desserts=.array~of(apples, peaches, pumpkins, 3.14159) /* Creates array */ 
say "The desserts we have are:" 
baker-desserts^ supplier /* Creates supplier object named BAKER */ 
do while baker^ available /* Array suppliers are sequenced ж/ 
if baker^index-4 
then say baker^item "is pi, not pie!!!" 
else say Бакег item 
baker^next 
end 


/* Produces: */ 


/* The desserts we have are: */ 


/* APPLES ж/ 
/* PEACHES ж/ 
/* PUMPKINS ж/ 


/* 3.14159 is pi, not pie!!! */ 


5.4.17.11. supplier 


PP SSUP PLOT ass sas SSeS Sa SSS Sea aS RS SSS SPSS ятата >< 


Returns the target supplier as a result. This method allows an existing supplier to be passed to methods 
that expect an object that implements a supplier method as an argument. 


5.4.18. The StreamSupplier Class 


A subclass of the Supplier class that will provided stream lines using supplier semantics. This allows the 
programmer to iterate over the remaining lines in a stream. A StreamSupplier object provides a snapshot 
of the stream at the point in time it is created, including the current line read position. In general, the 
iteration is not effected by later changes to the read and write positioning of the stream. However, forces 
external to the iteration may change the content of the remaining lines as the itertion progresses. 
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Figure 5-45. The StreamSupplier class and methods 
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Note: The StreamSupplier class also has available class methods that its metaclass, the Class 
class, defines. 


5.4.18.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) instanceMethod send 


=\= == \== <> >< instanceMethods sendWith 
class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


Methods inherited from the Supplier class. 


new (class method) available item 


allIndexes index next 

allItems init supplier 
5.4.18.2. available 
>>-ауалларів------Ә--------стзса За eee eoe >< 


Returns 1 (true) if an item is available from the supplier (that is, if the item method would return a value). 
It returns 0 (false) if the collection is empty or the supplier has already enumerated the entire collection. 
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5.4.18.3. index 


Po INd ORS Ses Sa SS SSSR SSR SSSR RRR SS SSS SRST SS SS SS SRS eerie >< 


Returns the index of the current item in the collection. If no item is available, that is, if available would 
return false, the supplier raises an error. 


5.4.18.4. init 


>>-іпі%-------------------------------------------------------- >< 


Initializes the object instance. 


5.4.18.5. item 


Returns the current item in the collection. If no item is available, that is, if available would return false, 
the supplier raises an error. 


5.4.18.6. next 


Moves to the next item in the collection. By repeatedly sending next to the supplier (as long as available 
returns true), you can enumerate all items in the collection. If no item is available, that is, if available 
would return false, the supplier raises an error. 


5.4.19. The RexxContext Class 


The RexxContext class gives access to context information about the currently executing Rexx code. 
Instances of the RexxContext class can only be obtained via the .CONTEXT environment symbol. They 
cannot be directly created by the user. It is a subclass of the Object class. 
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Figure 5-46. The RexxContext class and methods 
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5.4.19.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) — instanceMethod send 
=\= ==\== <> >< instanceMethods sendWith 


class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 
5.4.19.2. args 
POOL SR eS ee Te a eee ee >< 


Returns the arguments used to invoke the current context as an array. This is equivalent to using the 
Arg(1, ’A’) built-in function. 


5.4.19.3. condition 


2 -CONGD LE LON Sea Sa a SSeS SSS -- >< 
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Returns the current context condition object, or the Nil object if the context does not currently have a 
trapped condition. This is equivalent to using the Condition(’O’) built-in function. 


5.4.19.4. digits 


>>-digits------------------------------------------------------- >< 


Returns the current context digits setting. This is equivalent to using the digits() built-in function. 


5.4.19.5. executable 


2»-execubtablé------------—--9e--o--eeuneneneeeceeeo eee нА >< 


Returns the current executable object for the current context. The executable will be either a Routine or 
Method object, depending on the type of the active context. 


5.4.19.6. form 


»»-form------------------------------------------------------- >< 


Returns the current context form setting. This is equivalent to using the form() built-in function. 


5.4.19.7. fuzz 
»»-fuzz------------------------------------------------------- >< 


Returns the current context fuzz setting. This is equivalent to using the fuzz() built-in function. 


5.4.19.8. line 


»»-line------------------------------------------------------- >< 


Returns the context current execution line. This is equivalent to using the .LINE environment symbol. 


5.4.19.9. package 


>>2-раскате------------------ -----<- - << --- >< 


Returns Ше Package object associated with the current executable object. 


5.4.19.10. rs 
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Returns the context current return status value. If no host commands have been issued in the current 
context, the Nil object is returned. This is equivalent to using the .RS environment symbol. 


5.4.19.11. variables 


pas! 0 oes B= 9 | = a eee eire >< 


Returns a directory object containing all of the variables in the current execution context. The directory 
keys will be the variable names and the mapped values are the values of the variables. The directory will 
only contain simple variables and stem variables. Compound variable values may be accessed by using 
the stem objects that are returned for the stem variable names. 


5.4.20. The WeakReference Class 


A WeakReference instance maintains a non-pinning reference to another object. A non-pinning reference 
does not prevent an object from getting garbage collected or having its uninit method run when there are 
no longer normal references maintained to the object. Once the referenced object is eligible for garbage 
collection, the reference inside the WeakReference instance will be cleared and the VALUE method will 
return .nil on all subsequent calls. WeakReferences are useful for maintaining caches of objects without 
preventing the objects from being reclaimed by the garbage collector when needed. 


Figure 5-47. The WeakReference class and methods 
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Note: The WeakReference class also has available class methods that its metaclass, the Class 
class, defines. 
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5.4.20.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) — instanceMethod send 


=\===\== <> >< instaiceMethods sendWith 
class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


5.4.20.2. new (Class Method) 


»»-new-(object)------------------------------------------------ >< 


Returns a new WeakReference instance containing a reference to object. 


5.4.20.3. value 


This method returns the referenced object. If the object has been garbage collected, then the Nil object is 
returned. 


5.4.21. The Pointer Class 


Figure 5-48. The Pointer class and methods 
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A Pointer instance is a wrapper around a native pointer value. This class is designed primarily for writing 
methods and functions in native code and can only be created using the native code application 


programming interfaces. The Pointer class new method will raise an error if invoked. 


Note: The Pointer class also has available class methods that its metaclass, the Class class, defines. 


5.4.21.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) instanceMethod send 


=\===\== <> >< _ instanceMethods sendWith 
class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


5.4.21.2. new (Class Method) 


Creating Pointer object instances directly from Rexx code is not supported. The Pointer class new 
method will raise an error if invoked. 


5.4.21.3. Operator Methods 
>>-сошрагівоп орегафог(агрчшшпеп%)------------------------------- >< 


Returns 1 (true) or 0 (false), the result of performing a specified comparison operation. 


For the Pointer class, the argument object must be a pointer object instance and the wrappered pointer 
value must be the same. 


The comparison operators you can use in a message are: 


m True if the wrappered pointer values are the same. 


МЕ, ><, <>, шш True if the wrappered pointer values are not the same. 


5.4.21.4. isNull 


22s-crSNull--------——————-———coce -+----- esse >< 


Returns 1 (true) if the wrappered pointer value is a NULL pointer (0) value. Returns 0 (false) if the 
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pointer value is non-zero. 


5.4.22. The Buffer Class 


Figure 5-49. The Buffer class and methods 
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A Buffer instance is a Rexx interpreter managed block of storage. This class is designed primarily for 
writing methods and functions in native code and can only be created using the native code application 
programming interfaces. The Buffer class new method will raise an error if invoked. 


Note: The Buffer also has available class methods that its metaclass, the Class class, defines. 


5.4.22.1. Inherited Methods 


Methods inherited from the Object class. 


new (class method) — instanceMethod send 


=\===\== <> >< instanceMethods sendWith 
class isA setMethod 
copy isInstanceOf start 
defaultName objectName startWith 
hasMethod objectName= string 
identityHash Request unsetMethod 
init Run 


5.4.22.2. new (Class Method) 
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Creating Buffer object instances directly from Rexx code is not supported. The Buffer class new method 
will raise an error if invoked. 
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In addition to the class objects described in the previous chapter, the Rexx runtime environment also 
provides objects that are accessible via environment symbols (see Environment Symbols). 


6.1. The Environment Directory (.ENVIRONMENT) 


The Environment object is a directory of public objects that are always accessible. The Environment 
object is automatically searched when environment symbols are used, or the Environment object may be 
directly accessed using the .ENVIRONMENT symbol. Entries stored in the Environment use the same 
name as the corresponding environment symbol, but without a leading period. For example: 


say .true -- Displays "1" 
say .environment^ true -- Also displays "1" 


The Environment object directory contains all of the Rexx built-in classes (Array, etc.), plus special Rexx 
constants such as .NIL, . TRUE, and .FALSE. 


6.1.1. The ENDOFLINE Constant (.ENDOFLINE) 


The ENDOFLINE object is a string constant representing the line terminator used for file line end 
markers for a given system. This constant is "Od0a"x on Windows (carriage return/linefeed) and "Оа"х 
(linefeed) on Unix platforms. 


6.1.2. The FALSE Constant (.FALSE) 


The FALSE object is the constant "0" representing a FALSE result for logical and comparison operations. 


6.1.3. The NIL Object (.NIL) 


The Nil object is a special object that does not contain data. It usually represents the absence of an 
object, as a null string represents a string with no characters. It has only the methods of the Object class. 
Note that you use the Nil object (rather than the null string ("")) to test for the absence of data in ап array 
or other Collection class entry: 


пи 


if .nil = board[row,col] /ж „МП. rather than "" */ 
then ... 


6.1.4. The TRUE Constant (. TRUE) 


The TRUE object is the constant "1", representing a true result for logical and comparison operations. 


ooRexx Reference Version 4.0.0 363 


Chapter 6. Rexx Runtime Objects 


6.2. The Local Directory (.LOCAL) 


The Local environment object is a directory of interpreter instance objects that are always accessible. 
You can access objects in the Local environment object in the same way as objects in the Environment 
object. The Local object contains the INPUT, .OUTPUT, and .ERROR Monitor objects used for Rexx 
console I/O, the STDIN, .STDOUT, and .STDERR output streams that are the default I/O targets, and 
the STDQUE RexxQueue instance used for Rexx external queue operations. 


Because both ENVIRONMENT and .LOCAL are directory objects, you can place objects into, or 
retrieve objects from, these environments by using any of the directory methods (П,П-. PUT, AT, 
SETENTRY, ENTRY, or SETMETHOD). To avoid potential name clashes with built-in objects and 
public objects that Rexx provides, each object that your programs add to these environments should have 
a period in its index. 


Examples: 


/* .LOCAL example--places something in the Local environment directory */ 
.local^my.alarm = theAlarm 

/* To retrieve it */ 
say .local^my.alarm 


/* Another .LOCAL example (Windows) */ 
.environment ["MYAPP.PASSWORD"] = "topsecret" 
.environment["MYAPP.UID"] = 200 


/* Create a local directory for my stuff */ 
.local["MYAPP.LOCAL"] = .directory^new 


/* Add log file for my local directory ж/ 
.myapp.local["LOG"] = .stream^new("myapp.log") 

say .myapp.password /* Displays "topsecret" ж/ 
say .myapp.uid /* Displays "200" ж/ 


/* Write а line to the log file ж/ 
-myapp.local~log~lineout ("Logon at "time()" on "date()) 


/* Redirect SAY lines into a file: ж/ 


. output ~destination(.stream~new("SAY_REDIRECT.TXT") ) 
say "This goes into a file, and not onto the screen!" 


6.3. The Error Monitor (.ERROR) 


This monitor object (see The Monitor Class) holds the trace stream object. You can redirect the trace 
output in the same way as with the output object in the Monitor class example. 


The default for this object’s initial destination is the STDERR stream. 
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6.4. The Input Monitor (.INPUT) 


This monitor object (see The Monitor Class) holds the default input stream object (see Input and Output 
Streams). This input stream is the source for the PARSE LINEIN instruction, the LINEIN method of the 
Stream class, and, if you specify no stream name, the LINEIN built-in function. It is also the source for 
the PULL and PARSE PULL instructions if the external data queue is empty. 


The default for this object's initial source is the STDIN stream. 


6.5. The Output Monitor (.OUTPUT) 


This monitor object (see The Monitor Class) holds the default output stream object (see Input and Output 
Streams). This is the destination for output from the SAY instruction, the LINEOUT method 
(.OUTPUT-LINEOUT), and, if you specify no stream name, the LINEOUT built-in function. You can 
replace this object in the environment to direct such output elsewhere (for example, to a transcript 
window). 


The default for this object’s initial destination is the STDOUT stream. 


6.6. The STDERR Stream (.STDERR) 


This stream object (see The Stream Class) is the default stream used for trace and error message output. 


6.7. The STDIN Stream (.STDIN) 


This is the stream object (see The Stream Class) representing the representing the standard input file of a 
process. It is the startup default stream for the .INPUT object. 


6.8. The STDOUT Stream (.STDOUT) 


This is the stream object (see The Stream Class) representing the representing the standard output file of 
a process. It is the startup default stream for the .OUTPUT object. 


6.9. The STDQUE Queue (.STDQUE) 


This RexxQueue object (see The RexxQueue Class) is the destination for the PUSH and QUEUE 
instruction, and the source for queue lines for the PULL and PARSE PULL instructions. 
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6.10. The Rexx Context (.CONTEXT) 


The .CONTEXT environment symbol accesses a RexxContext instance for the currently active Rexx 
execution environment. See The RexxContext Class) for details on the RexxContext object. The returned 
context object is only active until the current method call, routine call, or program terminates. Once the 
context object is deactivated, an error will be raised if any of the RexxContext methods are called. 


6.11. The Line Number (.LINE) 


.LINE is set to the line number of the instruction currently being executed. If the current instruction is 
defined within an INTERPRET instruction, the line number of INTERPRET instruction is returned. 


6.12. The METHODS Directory (. METHODS) 


The .METHODS environment symbol identifies a directory (see The Directory Class) of methods that 
: METHOD directives in the currently running program define. The directory indexes are the method 
names. The directory values are the method objects. See The Method Class. 


Only methods and/or attributes that are not preceded by a ::CLASS directive are in ће . METHODS 
directory. These are known as floating methods. If there are no such methods, the . METHODS symbol 
has the default value of . METHODS. 


Example: 


/* .methods contains one entry with the index (method name) "TALK" */ 
o-.object^enhanced(.methods) /* create object, enhance it with methods */ 
o^talk("echo this text")  /* test "TALK" method */ 
::method talk /* floating method by the name of "TALK" */ 

use arg text /* retrieve the argument */ 

say text /* display received argument */ 


6.13. The Return Status (.RS) 


.RS is set to the return status from any executed command (including those submitted with the 
ADDRESS instruction). The .RS environment symbol has a value of -1 when a command returns a 
FAILURE condition, a value of 1 when a command returns an ERROR condition, and a value of 0 when 
a command indicates successful completion. The value of .RS is also available after trapping the ERROR 
or FAILURE condition. 


Note: Commands executed manually during interactive tracing do not change the value of .RS. The 
initial value of .RS is .Rs. 
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A function is an internal, built-in, or external routine that returns a single result object. (A subroutine is a 
function that is an internal, built-in, or external routine that might return a result and is called with the 
CALL instruction.) 


7.1. Syntax 


A function call is a term in an expression calling a routine that carries out some procedures and returns 
an object. This object replaces the function call in the continuing evaluation of the expression. You can 
include function calls to internal and external routines in an expression anywhere that a data term (such 
as a string) would be valid, using the following notation: 


»»-function name(----4------------ *-—--)----------------------- >< 


+-expression-+ 


The function_name is a literal string or a single symbol, which is taken to be a constant. 


There can be any number of expressions, separated by commas, between Ше parentheses. These 
expressions are called the arguments to the function. Each argument expression can include further 
function calls. 


Note that the left parenthesis must be adjacent to the name of the function, with no whitespace characters 
in between. (A blank operator would be assumed at this point instead.) Only a comment can appear 
between the name and the left parenthesis. 


The arguments are evaluated in turn from left to right and the resulting objects are then all passed to the 
function. This function then runs some operation (usually dependent on the argument objects passed, 
though arguments are not mandatory) and eventually returns a single object. This object is then included 
in the original expression as though the entire function reference had been replaced by the name of a 
variable whose value is the returned object. 


For example, the function SUBSTR is built into the language processor and could be used as: 


Ni-"abcdefghijk" 
Zi-"Part of Мі is: "substr(N1,2,7) 
/* Sets Z1 to "Part of N1 is: bcdefgh" */ 


A function can have a variable number of arguments. You need to specify only those required. For 
example, SUBSTR("ABCDEF" ,4) would return DEF. 


7.2. Functions and Subroutines 


Functions and subroutines are called in the same way. The only difference between functions and 
subroutines is that functions must return data, whereas subroutines need not. 


The following types of routines can be called as functions: 
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Internal 


If the routine name exists as a label in the program, the current processing status is saved for a later 
return to the point of invocation to resume execution. Control is then passed to the first label in the 
program that matches the name. As with a routine called by the CALL instruction, status 
information, such as TRACE and NUMERIC settings, is saved too. See the CALL instruction 
(CALL) for details. 


If you call an internal routine as a function, you must specify an expression in any RETURN 
instruction so that the routine can return. This is not necessary if it is called as a subroutine. 


Example: 

/* Recursive internal function execution... */ 

arg x 

say x"! -" factorial(x) 

exit 

factorial: procedure /ж Calculate factorial by ж/ 
arg n /* recursive invocation. ж/ 


if n-0 then return 1 
return factorial(n-1) * n 


FACTORIAL is unusual in that it calls itself (this is recursive invocation). The PROCEDURE 
instruction ensures that a new variable n is created for each invocation. 
Built-in 


These functions are always available and are defined in Built-in Functions. 


External 


You can write or use functions that are external to your program and to the language processor. An 
external routine can be written in any language, including Rexx, that supports the system-dependent 
interfaces the language processor uses to call it. You can call a Rexx program as a function and, in 
this case, pass more than one argument string. The ARG, PARSE ARG, or USE ARG instruction or 
the ARG built-in function can retrieve these argument strings. When called as a function, a program 
must return data to the caller. 


Notes: 


1. Calling an external Rexx program as a function is similar to calling an internal routine. For an 
external routine, however, the caller's variables are hidden. To leave the called Rexx program, 
you can use either EXIT or RETURN. In either case, you must specify an expression. 


2. You can use the INTERPRET instruction to process a function with a variable function name. 
However, avoid this if possible because it reduces the clarity of the program. 


7.2.1. Search Order 


Functions are searched in the following sequence: internal routines, built-in functions, external functions. 


Function calls or subroutines may use a name that is specified as a symbol or a literal string. For 
example, these calls are equivalent: 
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call MyProcedure 
call 'MYPROCEDURE' 


Note that the name value when specified as a symbol is the symbol name translated to upper case. Both 
of the calls above will search for a routine named "MYPROCEDURE". When Ше name is specified as a 
literal string, then the literal string value is used as-is. Thus the following two calls are not equivalent: 


call MyProcedure -- calls "MYPROCEDURE" 
call ’MyProcedure’ -- calls "MyProcedure" 


Some steps of the function and subroutine search order are case sensitive, so some care may need to be 
exercised that the correct name form is used: 


* Internal routines. Normally, labels are specified as a symbol followed by a ":". These labels have а 
name value that's all uppercase. Since unquoted (symbol) names also have uppercase values, these 
will match easily. It is also possible to use literal strings for label names. If these labels contain 
lowercase characters, they will not be located using normal call mechanisms 


* Built-in functions. The built-in function names are all uppercase, so using a mixed-case literal string 
built-in function name will fail to locate the function. 


wordPos(needle, haystack) -- calls "WORDPOS", which works 
"wordPos" (needle, haystack) -- calls "wordPos", which will fail 


x 


* External routines. Some steps of the external function search order may be case sensitive, depending 
on the system. This may occasionally require a function or subroutine name to be specified as a mixed 
case literal string to be located. 


If the call or function invocation uses a literal string, then the search for internal label is bypassed. This 
bypass mechanism allows you to extend the capabilities of an existing internal function, for example, and 
call it as a built-in function or external routine under the same name as the existing internal function. To 
call the target built-in or external routine from inside your internal routine, you must use a literal string 
for the function name. 


Example: 


/* This internal DATE function modifies the ж/ 

/* default for the DATE function to standard date. ж/ 

date: procedure 
arg in 
if in="" then in="Standard" 
-- This calls the DATE built-in function rather than recursively 
-- calling the DATE: internal routine. Note that the name needs to 
-- be all uppercase because built-in functions have uppercase names. 
return "DATE" (in) 


Since built-in functions have uppercase names the literal string must also be in uppercase for the search 
to succeed. 


External functions and subroutines have a system-defined search order. 


The search order for external functions is as follows: 


1. Functions defined on ::ROUTINE directives within the program. 
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2. Public functions defined on ::ROUTINE directives of programs referenced with ::REQUIRES. 


3. Functions that have been loaded into the macrospace for preorder execution. (See the Open Object 
Rexx: Programming Guide for details.) 


4. Functions that are part of a function package or library package. (See the Open Object Rexx: 
Programming Guide for details.) 


5. Rexx functions located in an external file. See below for how these external files are located. 


6. Functions that have been loaded into the macrospace for postorder execution. 


7.2.1.1. Locating External Rexx Files 


Rexx uses an extensive search procedure for locating program files. The first element of the search 
procedure is the locations that will be checked for files. The locations, in order of checking, are: 


к- 


. The same directory the program invoking the external routine is located. If this is an initial program 
execution or the calling program was loaded from the macrospace, this location is skipped. 
Checking in this directory allows related program files to be called without requiring the directory 
be added to the search path. 


n 


The current filesystem directory. 


W 


. The current filesystem directory. 


AB 


. Some applications using Rexx as a scripting language may define an extension path used to locate 
called programs. If the Rexx program was invoked directly from the system command line, the no 
extension path is defined. 


5. Any directories specified via the REXX PATH environment variable. 
6. Any directories specified via the PATH environment variable. 


The second element of the search process is the file extension. If the routine name contains contains at 
least one period, then this routine is extension qualified. The search locations above will be checked for 
the target file unchanged, and no additional steps will be taken. If the routine name is not extension 
qualified, then additional searches will be performed by adding file extensions to the name. The 
following extensions may be used: 


1. If the calling program has a file extension, then the interpreter will attempt to locate a file using the 
same extension as the caller. All directory locations will be checked for a given extension before 
moving to the next potential extension. 


2. Some applications Rexx as a scripting language may define extensions that should be added to the 
search order. For example, an editor might define a preferred extension that should be used for editor 
macros. This extension would be searched next. 


3. The default system extensions (. REX). 


4. If the target file has not been located using any of the above extensions, the file name is tried without 
an added extension. 


There are some system file system considerations involved when search for files. The Windows file 
system is case insensitive, so files can be located regardless of how the call is specified. Unix-based 
systems have a case sensitive file system, so files much be exact case matches in order to be located. For 
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these systems, each time a file name probe is attempted, the name will be tried in the case specified and 
also as a lower case name. 
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Figure 7-1. Function and Routine Resolution and Execution 
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7.2.2. Errors during Execution 


If an external or built-in function detects an error, the language processor is informed, and a syntax error 
results. Syntax errors can be trapped in the caller using SIGNAL ON SYNTAX and recovery might be 
possible. If the error is not trapped, the program is ended. 


7.3. Return Values 


A function usually returns a value that is substituted for the function call when the expression is 
evaluated. 


How the value returned by a function (or any Rexx routine) is handled depends on whether it is called by 
a function call or as a subroutine with the CALL instruction. 


* A routine called as a subroutine: If the routine returns a value, that value is stored in the special 
variable named RESULT. Otherwise, the RESULT variable is dropped, and its value is the string 
RESULT. 


* A routine called as a function: If the function returns a value, that value is substituted in the expression 
at the position where the function was called. Otherwise, the language processor stops with an error 
message. 


Here are some examples of how to call a Rexx procedure: 
call Beep 500, 100 /* Example 1: a subroutine call */ 


The built-in function BEEP is called as a Rexx subroutine. The return value from BEEP is placed in the 
Rexx special variable RESULT. 


bc = Beep(500, 100) /* Example 2: a function call ж/ 


BEEP is called as a Rexx function. The return value from the function is substituted for the function call. 
The clause itself is an assignment instruction; the return value from the BEEP function is placed in the 
variable bc. 


Beep(500, 100) /* Example 3: result passed as ж/ 
/ж a command */ 


The BEEP function is processed and its return value is substituted in the expression for the function call, 
like in the preceding example. In this case, however, the clause as a whole evaluates to a single 
expression. Therefore, the evaluated expression is passed to the current default environment as a 
command. 


Note: Many other languages, such as C, throw away the return value of a function if it is not assigned 
to a variable. In Rexx, however, a value returned like in the third example is passed on to the current 
environment or subcommand handler. If that environment is the default, the operating system 
performs a disk search for what seems to be a command. 
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7.4. Built-in Functions 


Rexx provides a set of built-in functions, including character manipulation, conversion, and information 
functions. The following are general notes on the built-in functions: 


* The parentheses in a function are always needed, even if no arguments are required. The first 
parenthesis must follow the name of the function with no whitespace in between. 


* The built-in functions internally work with NUMERIC DIGITS 9 for 32-bit systems or NUMERIC 
DIGITS 18 for 64-bit systems, and NUMERIC FUZZ 0 and are unaffected by changes to the 
NUMERIC settings, except where stated. Any argument named as a number is rounded, if necessary, 
according to the current setting of NUMERIC DIGITS (as though the number had been added to 0) 
and checked for validity before use. This occurs in the following functions: ABS, FORMAT, MAX, 
MIN, SIGN, and TRUNC, and for certain options of DATATYPE. 


* Any argument named as a string can be a null string. 


* If an argument specifies a length, it must be a positive whole number or zero. If it specifies a start 
character or word in a string, it must be a positive whole number, unless otherwise stated. 


* If the last argument is optional, you can always include a comma to indicate that you have omitted it. 
For example, DATATYPE(1,), like DATATYPE(1), would return NUM. You can include any number of 
trailing commas; they are ignored. If there are actual parameters, the default values apply. 


* If you specify a pad character, it must be exactly one character long. A pad character extends a string, 
usually on the right. For an example, see the LEFT built-in function LEFT. 


* Ifa function has an option that you can select by specifying the first character of a string, that 
character can be in uppercase or lowercase. 


* Many of the built-in functions invoked methos of the String class. For the functions ABBREV, ABS, 
BITAND, BITOR, BITXOR, B2X, CENTER, CENTRE, CHANGESTR, COMPARE, COPIES, 
COUNTSTR, C2D, C2X, DATATYPE, DELSTR, DELWORD, D2C, D2X, FORMAT, LEFT, 
LENGTH, LOWER, MAX, MIN, REVERSE, RIGHT, SIGN, SPACE, STRIP, SUBSTR, 
SUBWORD, TRANSLATE, TRUNC, UPPER, VERIFY, WORD, WORDINDEX, WORDLENGTH, 
WORDS, X2B, X2C, and X2D, the first argument to the built-in function is used as the receiver object 
for the message sent, and the remaining arguments are used in the same order as the message 
arguments. For example, SUBSTR("abcde",3,2) is equivalent to "abcde" - SUBSTR(3,2). 


For the functions INSERT, LASTPOS, OVERLAY, POS, and WORDPOS, the second argument to the 
built-in functions is used as the receiver object for the message sent, and the other arguments are used 
in the same order as the message arguments. For example, POS ("a" , "Haystack" ,3) is equivalent to 
"Haystack"~POS("a",3). 


* The language processor evaluates all built-in function arguments to produce character strings. 


7.4.1. ABBREV (Abbreviation) 


>>-ABBREV (information, info--+--------- %--)--------------------- >< 
+-,length-+ 


Returns 1 if info is equal to the leading characters of information and the length of info is not less than 
length. It returns 0 if either of these conditions is not met. 
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If you specify length, it must be a positive whole number or zero. The default for length is the number of 
characters in info. 


Here are some examples: 


ABBREV ("Print","Pri") -> 1 
ABBREV ("PRINT", "Pri") -> 0 
ABBREV("PRINT", "PRI", 4) -> 0 
ABBREV ( "PRINT" ,"PRY") -> 0 
ABBREV ("PRINT","") -> 1 
ABBREV ("PRINT","",1) -> 0 


Note: A null string always matches if a length of 0, or the default, is used. This allows a default 
keyword to be selected automatically if desired; for example: 
say "Enter option:"; pull option . 
select /ж keyword1 is to be the default */ 
when abbrev("keywordi",option) then ... 


when abbrev("keyword2",option) then ... 


otherwise nop; 
end; 


7.4.2. ABS (Absolute Value) 


>>-АВЅ (number)------------------------------------------------- >< 


Returns the absolute value of number. The result has no sign and is formatted according to the current 
NUMERIC settings. 


Here are some examples: 


ABS("12.3") -> 12.3 
ABS(" -0.307") -> 0.307 


7.4.3. ADDRESS 


>>-МОВЕ58()--------------------------------------------------- >< 


Returns the name of the environment to which commands are currently submitted. Trailing whitespace 
characters are removed from the result. 


Here is an example: 


ADDRESS () -» "CMD" /* default under Windows */ 


ADDRESS () -» "bash" /* default under Linux  */ 
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7.4.4. ARG (Argument) 


»»-ARG(--4---------------- 4--)--------------------------------- >< 
+-n--+--------- +-+ 


+-,option-+ 
Returns one or more arguments, or information about the arguments to a program, internal routine, or 
method. 
If you do not specify n, the number of arguments passed to the program or internal routine is returned. 


If you specify only n, the nth argument object is returned. If the argument object does not exist, the null 
string is returned. n must be a positive whole number. 


If you specify option, the value returned depends on the value of option. The following are valid options. 
(Only the capitalized letter is needed; all characters following it are ignored.) 


Array 


returns a single-index array containing the arguments, starting with the nth argument. The array 
indexes correspond to the argument positions, so that the nth argument is at index 1, the following 
argument at index 2, and so on. If any arguments are omitted, their corresponding indexes are 
absent. 

Exists 
returns 1 if the nth argument exists; that is, if it was explicitly specified when the routine was called. 
Otherwise, it returns 0. 


Normal 


returns the nth argument, if it exists, or a null string. 


Omitted 


returns 1 if the nth argument was omitted; that is, if it was not explicitly specified when the routine 
was called. Otherwise, it returns 0. 


Here are some examples: 


/* following "Call name;" (no arguments) */ 


ARG() -> 0 

ARG(1) -> un 

ARG(2) -> un 
ARG(1,"e") -> 0 
ARG(1,"0") -> 1 

ARG(1,"a" -» .array^of() 


/* following "Call name а, ,'b';" */ 


ARGO -> 3 

ARG(1) -> па" 

АВС (2) -> "n 

ARG(3) => "p" 

АВС (п) -> ти /* for n>=4 x/ 
ARG(1,"e") -> 1 
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ARG(2,"E") -> 0 

ARG(2,"0") -> 1 

ARG(3,"o") -> 0 

ARG(4,"o") -> 1 

ARG(1,"A") -> .array^of(a, ,b) 
ARG(3,"a" -> .array^of(b) 
Notes: 


1. The number of argument strings is the largest number n for which ARG (n, "e") returns 1 or 0 if there 
are no explicit argument strings. That is, it is the position of the last explicitly specified argument 
string. 


2. Programs called as commands can have only 0 or 1 argument strings. The program has 0 argument 
strings if it is called with the name only and has 1 argument string if anything else (including 
whitespace characters) is included in the command. 


3. Programs called by the RexxStart entry point can have several argument strings. (See the Open 
Object Rexx: Programming Guide for information about RexxStart.) 


4. You can access the argument objects of a program with the USE instruction. See USE for more 
information. 


5. You can retrieve and directly parse the argument strings of a program or internal routine with the 
ARG or PARSE ARG instructions. 


7.4.5. B2X (Binary to Hexadecimal) 
>>-В2Х(Білагу. string)------------------------------------------ >< 


Returns a string, in character format, that represents binary_string converted to hexadecimal. 


The binary_string is a string of binary (0 or 1) digits. It can be of any length. You can optionally include 
whitespace characters in binary_string (at 4-digit boundaries only, not leading or trailing) to improve 
readability; they are ignored. 


The returned string uses uppercase alphabetical characters for the values A-F, and does not include blanks 
or horizontal tabs. 


If binary_string is the null string, B2X returns a null string. If the number of binary digits in 
binary_string is not a multiple of 4, then up to three 0 digits are added on the left before the conversion 
to make a total that is a multiple of 4. 


Here are some examples: 


B2X("11000011") => "Сз" 
В2Х ("10111") -> нат" 
В2Х ("101") -> "Б" 


В2Х ("1 1111 0000") -> "1Е0" 


You can combine B2X with Ше functions X2D and X2C to convert a binary number into other forms. For 
example: 


X2D(B2X("10111")) -> "23" /* decimal 23 */ 
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7.4.6. BEEP 


>>-ВЕЕР (frequency ,duration)------------------------------------ >< 


Sounds the speaker at frequency (Hertz) for duration (milliseconds). The frequency can be any whole 
number in the range 37 to 32767 Hertz. The duration can be any number in the range | to 60000 
milliseconds. 


This routine is most useful when called as a subroutine. A null string is returned. 


Note: Both parameters (frequency, duration) are ignored on Windows 95 and Linux. On computers 
with multimedia support the function plays the default sound event. On computers without 
soundcard, the function plays the standard system beep (if activated). 


Here is an example for Windows NT: 


/* C scale */ 


note.1 - 262 /* middle C */ 
note.2 - 294 /* D ж/ 
note.3 = 330 /* E ж/ 
note.4 = 349 /* F ж/ 
note.5 = 392 /* G ж/ 
note.6 = 440 /* A ж/ 
note.7 = 494 /* B ж/ 
note.8 = 523 /* C ж/ 
do i=1 to 8 


call beep note.i,250 /* hold each note for */ 
/* one-quarter second */ 
end 


7.4.7. BITAND (Bit by Bit AND) 


>>-BITAND (string1--+-------------------------- %--)------------- >< 


Returns a string composed of the two input strings logically ANDed, bit by bit. (The encodings of the 
strings are used in the logical operation.) The length of the result is the length of the longer of the two 
strings. If no pad character is provided, the AND operation stops when the shorter of the two strings is 
exhausted, and the unprocessed portion of the longer string is appended to the partial result. If pad is 
provided, it extends the shorter of the two strings on the right before carrying out the logical operation. 
The default for string2 is the zero-length (null) string. 


Here are some examples: 


BITAND("12"x) -> "12"x 
BITAND("73"x,"27"x) -> "23"x 
BITAND("13"x,"5555"x) -> "1155"x 
BITAND("13"x,"5555"x,"74"x) -> "1154"х 
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BITAND("pQrS", ,"DF"x) -> "PQRS" /* ASCII ж/ 


7.4.8. BITOR (Bit by Bit OR) 


»»-BITOR(stringi--4-------------------------- a >< 
%-,--%--------- %--%------ +-+ 


E 


*-string2-* +-,рад-+ 


Returns a string composed of the two input strings logically inclusive-ORed, bit by bit. (The encodings 
of the strings are used in the logical operation.) The length of the result is the length of the longer of the 
two strings. If no pad character is provided, the OR operation stops when the shorter of the two strings is 
exhausted, and the unprocessed portion of the longer string is appended to the partial result. If pad is 
provided, it extends the shorter of the two strings on the right before carrying out the logical operation. 
The default for string2 is the zero-length (null) string. 


Here are some examples: 


BITOR("12"x) -»  "12"x 
BITOR("15"x,"24"x) ->  "B35'"x 
BITOR("15"x,"2456"x) -> "3556"x 
BITOR("15"x,"2456"x,"FO"x) -> "ЗБЕб"х 
BITOR("1111"x, ,"4D"x) -> "SDSD"x 
BITOR("pQrS", ,"20"x) -> "pqrs" /ж ASCII  */ 


7.4.9. BITXOR (Bit by Bit Exclusive OR) 


>>-BITXOR (string1--+-------------------------- %--)------------- >< 
%-,--%--------- %--%------ +-+ 
+-string2-+ +-,рад-+ 


Returns a string composed of the two input strings logically eXclusive-ORed, bit by bit. (The encodings 
of the strings are used in the logical operation.) The length of the result is the length of the longer of the 
two strings. If no pad character is provided, the XOR operation stops when the shorter of the two strings 
is exhausted, and the unprocessed portion of the longer string is appended to the partial result. If pad is 
provided, it extends the shorter of the two strings on the right before carrying out the logical operation. 
The default for string2 is the zero-length (null) string. 


Here are some examples: 





BITXOR("12"x) -> "12"x 
BITXOR("12"x,"22"x) -> "30"x 
BITXOR("1211"x,"22"x) -> "3011"x 
BITXOR("1111"x,"444444"x) -> "555544"х 
BITXOR("1111"x,"444444"x , "40" x) -> "555504"х 
BITXOR("1111"x, ,"AD"x) -> "БС5С"х 
BITXOR("C711"x,"222222"x," ") -> "Е53302"х /ж ASCII */ 
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7.4.10. C2D (Character to Decimal) 


»»-C2D(string--*----4--)--------------------------------------- >< 
+- ,n-+ 


Returns the decimal value of the binary representation of string. If the result cannot be expressed as a 
whole number, an error results. That is, the result must not have more digits than the current setting of 
NUMERIC DIGITS. If you specify n, it is the length of the returned result. If you do not specify n, string 
is processed as an unsigned binary number. 


If string is null, 0 is returned. 


Here are some examples: 


C2D("09"X) -> 9 
C2D("81"X) -> 129 
C2D("FF81"X) -> 65409 
C2D("") -> 0 
C2D("a" -» 97 /* ASCII */ 


If you specify n, the string is taken as a signed number expressed in и characters. The number is positive 
if the leftmost bit is off, and negative if the leftmost bit is on. In both cases, it is converted to a whole 
number, which can be negative. The string is padded on the left with "00"x characters (not 
"sign-extended"), or truncated on the left to п characters. This padding or truncation is as though 
RIGHT(string, n,"00"x) had been processed. If n is 0, C2D always returns 0. 


Here are some examples: 


C2D("81"X, 1) -> -127 
C2D("81"X, 2) -> 129 
C2D("FF81"X,2) -> -127 
C2D("FF81"X,1) -> -127 
C2D("FF7F"X, 1) -> 127 
C2D("F081"X,2) -> -3967 
C2D("FO81"X,1) -> -127 
C2D("0031"X,0) -> 0 


7.4.11. C2X (Character to Hexadecimal) 


»»-C2X(string)------------------------------------------------- >< 


Returns a string, in character format, that represents string converted to hexadecimal. The returned string 
contains twice as many bytes as the input string. On an ASCII system, C2X(1) returns 31 because the 
ASCII representation of the character 1 is "31"X. 


The string returned uses uppercase alphabetical characters for the values A-F and does not include 
whitespace characters. The string can be of any length. If string is null, a null string is returned. 


Here are some examples: 


C2X("0123"X) -> "0123" /* "30313233"X in ASCII */ 
C2X("ZD8") => "544438" /ж "354134343338"X in ASCII */ 
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7.4.12. CENTER (or CENTRE) 


>>-+-CENTER (-+--string, length--+------ %--)--------------------- >< 
+-CENTRE (-+ +-,рад-+ 


Returns a string of length length with string centered in it and with pad characters added as necessary to 
make up length. The length must be a positive whole number or zero. The default pad character is blank. 
If the string is longer than length, it is truncated at both ends to fit. If an odd number of characters is 
truncated or added, the right-hand end loses or gains one more character than the left-hand end. 


Here are some examples: 


CENTER (abc ,7) -> " ABC " 
CENTER (abc,8,"-") -> "--АВС---! 
CENTRE("The blue sky",8) -> "e blue s" 
CENTRE("The blue sky",7) -> "е blue " 


Note: To avoid errors because of the difference between British and American spellings, this function 
can be called either CENTRE or CENTER. 


7.4.13. CHANGESTR 


>>-CHANGESTR (needle , haystack ,newneedle--+-------- %--)------------------------ >< 


Returns а copy of haystack in which newneedle replaces occurrences of needle. If count is not specified, 
all occurrences of needle are replaced. If count is specified, it must be a positive, whole number that 
gives the maximum number of occurrences to be replaced. The following defines the effect: 


result = "" 
1 
do forever 


$tempx 


$tempy = pos(needle, haystack, $tempx) 
if $tempy = 0 then leave 
result = result || substr(haystack, $tempx, $tempy - $tempx) || newneedle 
$tempx = $tempy + length(needle) 
end 
result = result || substr(haystack, $tempx) 


Here are some examples: 


CHANGESTR("1","101100","") -> "000" 
CHANGESTR("1", "101100", "Х") -> "XOXXOO" 
CHANGESTR("1","101100","X", 1) -> "X01100" 
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7.4.14. CHARIN (Character Input) 


»»-CHARIN(--4------ %--%--------------------------- %--)--------- >< 
+-name-+ +-,--+------- +--+--------- +-+ 
t+-start-+ +-,length-+ 


Returns a string of up to length characters read from the character input stream name. (To understand the 
input and output functions, see Input and Output Streams.) If you omit name, characters are read from 
STDIN, which is the default input stream. The default length is 1. 


For persistent streams, a read position is maintained for each stream. Any read from the stream starts at 
the current read position by default. When the language processor completes reading, the read position is 
increased by the number of characters read. You can give a start value to specify an explicit read position. 
This read position must be a positive whole number and within the bounds of the stream, and must not be 
specified for a transient stream. A value of 1 for start refers to the first character in the stream. If start is 
not a positive whole number the appropriate syntax condition is raised. When the read position is past the 
bounds of the stream, the empty string is returned and the NOTREADY condition is raised. 


If you specify a length of 0, then the read position is set to the value of start, but no characters are read 
and the null string is returned. 


In a transient stream, if there are fewer than length characters available, the execution of the program 
generally stops until sufficient characters become available. If, however, it is impossible for those 
characters to become available because of an error or another problem, the NOTREADY condition is 
raised (see Errors during Input and Output) and CHARIN returns with fewer than the requested number 
of characters. 


Here are some examples: 


CHARIN(myfile,1,3) -> "МЕС" /* the first 3 ж/ 

/* characters ж/ 
CHARIN(myfile,1,0) -> 7 /* now at start ж/ 
CHARIN (myfile) -> "M" /* after last call */ 
CHARIN (myfile, ,2) -> "FC" /* after last call ж/ 


/* Reading from the default input (here, the keyboard) ж/ 


/* User types "abcd efg" */ 

CHARIN() => "a" /* default is ж/ 
/ж 1 character ж/ 

CHARIN(, ,5) -> "bcd e" 

Notes: 


1. CHARIN returns all characters that appear in the stream, including control characters such as line 
feed, carriage return, and end of file. 


2. When CHARIN reads from the keyboard, program execution stops until you press the Enter key. 


7.4.15. CHAROUT (Character Output) 


>>-CHAROUT (--+------ saa a ---------- %--)-------- >< 
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Returns the count of characters remaining after attempting to write string to the character output stream 
name. (To understand the input and output functions, see Input and Output Streams.) If you omit name, 
characters in string are written to STDOUT (generally the display), which is the default output stream. 
The string can be a null string, in which case no characters are written to the stream, and 0 is always 
returned. 


For persistent streams, a write position is maintained for each stream. Any write to the stream starts at 
the current write position by default. When the language processor completes writing, the write position 
is increased by the number of characters written. When the stream is first opened, the write position is at 
the end of the stream so that calls to CHAROUT append characters to the end of the stream. 


You can give a start value to specify an explicit write position for a persistent stream. This write position 
must be a positive whole number. A value of 1 for start refers to the first character in the stream. 


You can omit the string for persistent streams. In this case, the write position is set to the value of start 
that was given, no characters are written to the stream, and 0 is returned. If you do not specify start or 
string, the stream is closed and 0 is returned. 


Execution of the program usually stops until the output operation is complete. 


For example, when data is sent to a printer, the system accepts the data and returns control to Rexx, even 
though the output data might not have been printed. Rexx considers this to be complete, even though the 
data has not been printed. If, however, it is impossible for all the characters to be written, the 
NOTREADY condition is raised (see Errors during Input and Output) and CHAROUT returns with the 
number of characters that could not be written (the residual count). 


Here are some examples: 


CHAROUT (myfile, "Hi") -> 0 /ж typically */ 
CHAROUT(myfile,"Hi",5) -> 0 /* typically */ 
CHAROUT (myfile, ,6) -> (0) /* now at char 6 */ 
CHAROUT (myfile) -> 0 /* at end of stream */ 
CHAROUT(, "Hi") -> 0  /* typically */ 
CHAROUT(, "Hello") -> 2  /* maybe ж/ 


Note: This routine is often best called as а subroutine. The residual count is then available in the 
variable RESULT. 


For example: 


Call CHAROUT myfile,"Hello" 
Call CHAROUT myfile,"Hi",6 
Call CHAROUT myfile 


7.4.16. CHARS (Characters Remaining) 


>>-CHARS (--+------ %--)----------------------------------------- >< 
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Returns the total number of characters remaining in the character input stream name. The count includes 
any line separator characters, if these are defined for the stream. In the case of persistent streams, it is the 
count of characters from the current read position. (See Input and Output Streams for a discussion of 
Rexx input and output.) If you omit name, the number of characters available in the default input stream 
(STDIN) is returned. 


The total number of characters remaining cannot be determined for some streams (for example, STDIN). 
For these streams, the CHARS function returns 1 to indicate that data is present, or 0 if no data is present. 
For windows devices, CHARS always returns 1. 


Here are some examples: 


CHARS (myfile) -> 42 /* perhaps */ 
CHARS (поп ile) -> 0 
CHARS () => A /* perhaps */ 


7.4.17. COMPARE 


>>-COMPARE(string1,string2--+------ %--)------------------------ >< 
+-,pad-+ 


Returns 0 if the strings string/ and string2 are identical. Otherwise, it returns the position of the first 
character that does not match. The shorter string is padded on the right with pad if necessary. The default 
pad character is a blank. 


Here are some examples: 


COMPARE ("abc", "abc") -> 0 
СОМРАВЕ("аһс","ак") -> 2 
COMPARE("ab ", аһ") -> 0 
COMPARE("ab ","ab"," ") s» 0 
COMPARE("ab ","ab","x") -> 3 
COMPARE("ab-- ","ab","-") -> 5 


7.4.18. CONDITION 


>>-CONDITION (--+-------- %--)----------------------------------- >< 
+-option-+ 


Returns the condition information associated with the current trapped condition. (See Conditions and 
Condition Traps for a description of condition traps.) You can request the following pieces of 
information: 


* The name of the current trapped condition 
* Any descriptive string associated with that condition 
* Any condition-specific information associated with the current trapped condition 


* The instruction processed as a result of the condition trap (CALL or SIGNAL) 
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* The status of the trapped condition 
In addition, you can request a condition object containing all of the preceding information. 


To select the information to be returned, use the following options. (Only the capitalized letter is needed; 
all characters following it are ignored.) 


Additional 
returns any additional object information associated with the current trapped condition. See 
Additional Object Information for a list of possible values. If no additional object information is 
available or no condition has been trapped, the language processor returns the Nil object. 
Condition name 
returns the name of the current trapped condition. For user conditions, the returned string is a 
concatenation of the word USER and the user condition name, separated by a whitespace character. 
Description 


returns any descriptive string associated with the current trapped condition. See Descriptive Strings 
for the list of possible values. If no description is available or no condition has been trapped, it 
returns a null string. 


Instruction 


returns either CALL or SIGNAL, the keyword for the instruction processed when the current condition 
was trapped. This is the default if you omit option. If no condition has been trapped, it returns a null 
string. 

Object 
returns an object that contains all the information about the current trapped condition. See 
Conditions and Condition Traps for more information. If no condition has been trapped, it returns 
the Nil object. 

Status 


returns the status of the current trapped condition. This can change during processing, and is one of 
the following: 


* ON - the condition is enabled 

* OFF - the condition is disabled 

* DELAY - any new occurrence of the condition is delayed or ignored 
If no condition has been trapped, a null string is returned. 


Here are some examples: 


CONDITION () -> "CALL" /* perhaps */ 
CONDITION ("С") -> "FAILURE" 

CONDITION("I") -> "CALL" 

CONDITION ("0") -> "FailureTest" 
CONDITION("S") -> "OFF" /* perhaps */ 
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Note: The CONDITION function returns condition information that is saved and restored across 
subroutine calls (including those a CALL ON condition trap causes). Therefore, after a subroutine 
called with CALL ON trapname has returned, the current trapped condition reverts to the condition 
that was current before the CALL took place (which can be none). CONDITION returns the values it 
returned before the condition was trapped. 


7.4.19. COPIES 


»»-COPIES(string,n)-------------------------------------------- >< 


Returns n concatenated copies of string. The n must be a positive whole number or zero. 


Here are some examples: 


COPIES ("abc", 3) -> "abcabcabc" 
COPIES ("арс",0) -> "n 


7.4.20. COUNTSTR 
>>-COUNTSTR (needle,haystack)----------------------------------- >< 


Returns a count of the occurrences of needle in haystack that do not overlap. The following defines the 
effect: 


result=0 

$tempx=pos (needle, haystack) 

do while $temp > 0 

result-result-*i 

$temp=pos (needle, haystack, $temptlength (needle) ) 
end 


Here are some examples: 


COUNTSTR("1","101101") -> 
COUNTSTR("KK" , " JOKKKO") -> 1 


7.4.21. D2C (Decimal to Character) 


>>-D2C rholenumber--4----4--)---------------------------------- >< 
*-,n--* 


Returns a string, in character format, that is the ASCII representation of the decimal number. If you 
specify n, it is the length of the final result in characters; leading "00"x (for a positive wholenumber) or 
"FF"x (for a negative wholenumber) characters are added to the result string as necessary. n must be a 
positive whole number or zero. 
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Wholenumber must not have more digits than the current setting of NUMERIC DIGITS. 


If you omit n, wholenumber must be a positive whole number or zero, and the result length is as needed. 
Therefore, the returned result has no leading "00"x characters. 


Here are some examples: 


D2C(65) -> VE" 
D2C(65,1) -> тА" 
D2C(65,2) -> ҒА 
D2C(65,5) -> " 

02С(109) -> "m" 
D2C(-109,1) -> "6" 
D2C(76,2) -> "L 
D2C(-180,2) -> "L 


A" 


/* 


/ж 
/ж 
/ж 
/ж 
/ж 
/ж 


"41"x is an ASCII "A" 


the leading character is a "00"x 
the leading characters are "00"x 


"6D"x is an ASCII "m" 
"93"x is an ASCII "6" ж/ 
"4C"x is ап ASCII "L" 


the leading character is a "FF"x 


*/ 


*/ 
*/ 
*/ 


*/ 
*/ 


Implementation maximum: The output string must not have more than 250 significant characters, 
although it can be longer if it contains leading sign characters ("00"x апа "FF"x). 


7.4.22. D2X (Decimal to Hexadecimal) 


>>-D2X (rholenumber--4----4--)---------------------------------- >< 


n-* 


Returns a string, in character format, that represents wholenumber, a decimal number, converted to 
hexadecimal. The returned string uses uppercase alphabetics for the values A-F and does not include 


whitespace characters. 


Wholenumber must not have more digits than the current setting of NUMERIC DIGITS. 


If you specify n, it is the length of the final result in characters. After conversion the input string is 
sign-extended to the required length. If the number is too big to fit characters, it is truncated on the left. 
n must be a positive whole number or zero. 


If you omit n, wholenumber must be a positive whole number or zero, and the returned result has no 


leading zeros. 


Here are some examples: 


D2X(9) -> 
D2X(129) -» 
D2X (129,1) -> 
D2X(129,2) -> 
D2X (129,4) -> 
D2X (257,2) -> 
02Х(-127,2) -> 
02Х(-127,4) -> 
02Х(12,0) -> 


но" 
"g4" 
"gn 
"g4" 
"0081" 
ної" 
"81" 
"FF81" 


Implementation maximum: The output string must not have more than 500 significant hexadecimal 
characters, although it can be longer if it contains leading sign characters (0 and F). 
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7.4.23. DATATYPE 


>>-DATATYPE (string--+------- %--)------------------------------- >< 
+-,type-+ 


Returns NUM if you specify only string and if string is a valid Rexx number that can be added to 0 without 
error; returns CHAR if string is not a valid number. 


If you specify type, it returns 1 if string matches the type. Otherwise, it returns 0. If string is null, the 
function returns 0 (except when the type is X or B, for which DATATYPE returns 1 for a null string). The 
following are valid types. (Only the capitalized letter, or the number of the last type listed, is needed; all 
characters surrounding it are ignored. Note that for the hexadecimal option, you must start your string 
specifying the name of the option with x rather than h.) 


Alphanumeric 


returns 1 if string contains only characters from the ranges a-z, A-Z, and 0-9. 


Binary 
returns 1 if string contains only the characters 0 or 1, or whitespace. Whitespace characters can 
appear only between groups of 4 binary characters. It also returns 1 if string is a null string, which is 
a valid binary string. 

Lowercase 


returns 1 if string contains only characters from the range a-z. 


Mixed case 


returns 1 if string contains only characters from the ranges a-z and A-Z. 


Number 
returns 1 if DATATYPE(string) returns NUM. 
lOgical 
returns 1 if the string is exactly "0" or "1". Otherwise it returns 0. 


Symbol 


returns 1 if string is a valid symbol, that is, if SYMBOL (string) does not return BAD. (See Symbols.) 
Note that both uppercase and lowercase alphabetics are permitted. 


Uppercase 


returns 1 if string contains only characters from the range A-Z. 


Variable 


returns 1 if string could appear on the left-hand side of an assignment without causing a SYNTAX 
condition. 


Whole number 


returns 1 if string is a Rexx whole number under the current setting of NUMERIC DIGITS. 
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heXadecimal 
returns 1 if string contains only characters from the ranges a-f, A-F, 0-9, and whitespace (as long as 
the whitespace characters appear only between pairs of hexadecimal characters). It also returns 1 if 
string is a null string, which is a valid hexadecimal string. 

9 digits 
returns 1 if DATATYPE(string,"W") returns 1 when NUMERIC DIGITS is set to 9. 


Here are some examples: 


DATATYPE(" 12 ") -» "МОМ" 
РАТАТҮРЕ ("") -> "CHAR" 
РАТАТҮРЕ ("123%") -> "CHAR" 
DATATYPE("12.3","N") -> 1 
DATATYPE("12.3","W") -> 0 
DATATYPE("Fred","M") -> 1 
DATATYPE("Fred" ,"U") -> 0 
ОДТАТУРЕ ( "Егей", "L") -> 0 
DATATYPE("?20K" , "s") -> 1 
DATATYPE("BCd3" , "X") -> 1 
DATATYPE("BC d3","X") -> 1 
РАТАТҮРЕ ("1", "0") => 1 
DATATYPE("11,"0") -> 0 








Note: The DATATYPE function tests the meaning or type of characters in а string, independent of the 
encoding of those characters (for example, ASCII or EBCDIC). 


7.4.24. DATE 


»»-DATE(-------------------------------------------------------- ? 
>--%------------------------------------------------------------- +--> 
F Optone ag a ee +-+ 

%-,вігіпр--%---------- ж en sS Resse se sa SS ase + 


| +-,option2-+ | 
%-%-,--,------------------ +--+-,овер------------ +-+ 


+-,string--+-,option2-+-+ +-+-,osep-+--,isep-+ 


Returns, by default, the local date in the format: dd mon yyyy (day month year--for example, 13 Nov 
1998), with no leading zero or blank on the day. The first three characters of the English name of the 
month are used. 


You can use the following options to obtain specific formats. (Only the capitalized letter is needed; all 
characters following it are ignored.) 
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Base 


returns the number of complete days (that is, not including the current day) since and including the 
base date, 1 January 0001, in the format: dddddd (no leading zeros or whitespace). The expression 
РАТЕ ("В") //7 returns a number in the range 0-6 that corresponds to the current day of the week, 
where 0 is Monday and 6 is Sunday. 


Note: The base date of 1 January 0001 is determined by extending the current Gregorian 
calendar backward (365 days each year, with an extra day every year that is divisible by 4 
except century years that are not divisible by 400. It does not take into account any errors in the 
calendar system that created the Gregorian calendar originally. 


Days 


returns the number of days, including the current day, that have passed this year in the format ddd 
(no leading zeros or whitespace). 


European 


returns the date in the format dd/mm/yy. 


Full 


returns the number of microseconds since 00:00:00.000000 on 1 January 0001, in the format: 
dddddddddddddddddd (no leading zeros or whitespace). 


Notes: The base date of 1 January 0001 is determined by extending the current Gregorian 
calendar backward (365 days each year, with an extra day every year that is divisible by 4 
except century years that are not divisible by 400. It does not take into account any errors in the 
calendar system that created the Gregorian calendar originally. 


The value returned by Date(’F’) can be used to calculate the interval between any two dates. 
Note, however, that values returned generally contain more digits that the default NUMERIC 
DIGITS setting. The NUMERIC DIGITS setting should be increased to a minimum value of 18 
when performing timestamp arithmetic. 


Language 


returns the date in an implementation- and language-dependent, or local, date format. The format is 
dd month yyyy. The name of the month is according to the national language installed on the 
system. If no local date format is available, the default format is returned. 


Note: This format is intended to be used as a whole; Rexx programs must not make any 
assumptions about the form or content of the returned string. 
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Month 


returns the full English name of the current month, for example, August. 


Normal 


returns the date in the format dd mon yyyy. This is the default. 


Ordered 


returns the date in the format yy/mm/dd (suitable for sorting, for example). 


Standard 


returns the date in the format yyyymmdd (suitable for sorting, for example). 


Ticks 


returns the number of seconds since 00:00:00.000000 on 1 January 1970, in the format: 
dddddddddddd (no leading zeros or whitespace). 


Notes: The base date of 1 January 1970 is determined by extending the current Gregorian 
calendar backward (365 days each year, with an extra day every year that is divisible by 4 
except century years that are not divisible by 400. It does not take into account any errors in the 
calendar system that created the Gregorian calendar originally. 


The value returned by Date(’T’) can be used to calculate the interval between any two dates. 
Note, however, that values returned generally contain more digits that the default NUMERIC 
DIGITS setting. The NUMERIC DIGITS setting should be increased to a minimum value of 12 
when performing timestamp arithmetic. 


Date(’T’) will return a negative number for dates prior to 1 January 1970. 


Usa 


returns the date in the format mm/dd/yy. 


Weekday 
returns the English name for the day of the week, in mixed case, for example, Tuesday. 


Here are some examples, assuming today is 13 November 1996: 





DATEO -> "13 Nov 1996" 
DATE("B") -> 728975 
DATE("D") -> 318 

DATE("E") -> "13/11/96" 
DATE("L") -> "13 November 1996" 
DATE("M") -> "November" 
DATE("N") -> "13 Nov 1996" 
DATE("0") => "96/11/13" 
DATE("S") -> "19961113" 
DATE("U") => "11/13/96" 
DATE("W") -> "Wednesday" 
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Note: The first call to DATE or TIME in one clause causes a time stamp to be made that is then used 
for all calls to these functions in that clause. Therefore, several calls to any of the DATE or TIME 
functions, or both, in a single expression or clause are consistent with each other. 


If you specify string, DATE returns the date corresponding to string in the format option. The string 
must be supplied in the format option2. The option2 format must specify day, month, and year (that is, 
not "D", "L", "M", or "W"). The default for option2 is "№", so you need to specify option2 if string is not 
in the Normal format. Here are some examples: 


DATE("0","13 Feb 1923") -> "23/02/13" 
DATE("0","06/01/50","U") -> "50/06/01" 
DATE("N", "63326132161828000", "f") -» "23 Sep 2007" 


If you specify an output separator character osep, the days, month, and year returned are separated by 
this character. Any nonalphanumeric character or an empty string can be used. A separator character is 
only valid for the formats "E", "№", "О", "S", and "О". Неге are some examples: 


DATE("S","13 Feb 1996","N","-") -> "1996-02-13" 
DATE("N","13 Feb 1996","N","") -> "13Feb1996" 
DATE("N","13 Feb 1996", "М","-") -> "13-Feb-1996" 

РАТЕ ("0", "06/01/50", "U" ,"") -> "500601" 

DATE("E", "02/13/96", "0",".") -> "13.02.96" 

DATE("N", , ," ") -> "26 Маг 1998" (today) 


In this way, formats сап be created that аге derived from their respective default format, which is the 
format associated with option using its default separator character. The default separator character for 
each of these formats is: 


Option Default separator 
European "у" 
Могта1 т 
Ordered ny" 
Standard "" (empty string) 
Usa un 


If you specify a string containing a separator that is different from the default separator character of 
option2, you must also specify isep to indicate which separator character is valid for string. Basically, 
any date format that can be generated with any valid separator character can be used as input date string 
as long as its format has the generalized form specified by option2 and its separator character matches 
the character specified by isep. 


Here are some examples: 


РАТЕ ("5", "1996-11-13", "5", "","-") -> "19961113" 
DATE("S" ,"13-Nov-1996" , "М", "","-") -» "19961113" 
DATE("O", "06*01*50" алты” " тағ) -> "500601" 

DATE("U","13.Feb.1996","N", ,".") -» "02/13/96" 


You can determine the number of days between two dates; for example: 


say date("B","12/25/96","U")-date("B") " shopping days till Christmas!" 
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If string does not include the century but option defines that the century be returned as part of the date, 
the century is determined depending on whether the year to be returned is within the past 50 years or the 
next 49 years. Assume, for example, that you specify 10/15/43 for string and today’s date is 10/27/1998. 
In this case, 1943 would be 55 years ago and 2043 would be 45 years in the future. So, 10/15/2043 
would be the returned date. 


Note: This rule is suitable for dates that are close to today’s date. However, when working with birth 
dates, it is recommended that you explicitly provide the century. 


When requesting dates to be converted to Full format or Ticks format, a time value of "00:00:00.000000" 
is used for the conversion. A time stamp for a time and date combination can be created by combining a 
value from Time() for the time of day. 


numeric digits 18 -- needed to add the timestamps 
timestamp = date(’f, ?20072301?, ^S?) + time(’f’, 208:14:22, ^N?) 


7.4.25. DELSTR (Delete String) 


>>-DELSTR (string ,n--+--------- %--)---<------------------------- >< 
+-,length-+ 


Returns string after deleting the substring that begins at the nth character and is of length characters. If 
you omit length, or if length is greater than the number of characters from n to the end of string, the 
function deletes the rest of string (including the nth character). The length must be a positive whole 
number or zero. п must be a positive whole number. If и is greater than the length of string, the function 
returns string unchanged. 


Here are some examples: 


DELSTR("abcd",3) -> "ар" 
DELSTR("abcde",3,2) -> "abe" 
DELSTR("abcde", 6) -> "abcde" 


7.4.26. DELWORD (Delete Word) 


»»-DELWORD(string,n--4--------- =) танана а-атасы-Ш-- >< 
+-,length-+ 


Returns string after deleting the substring that starts at the nth word and is of length whitespace-delimited 
words. If you omit length, or if length is greater than the number of words from n to the end of string, the 
function deletes the remaining words in string (including the nth word). The length must be a positive 
whole number or zero. п must be a positive whole number. If n is greater than the number of words in 
string, the function returns string unchanged. The string deleted includes any whitespace characters 
following the final word involved but none of the whitespace preceding the first word involved. 


Here are some examples: 
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DELWORD("Now is the time",2,2) -> "Now time" 
DELWORD("Now is the time ",3) -> "Now is " 
DELWORD("Now is the time",5) -> "Now is the time" 
DELWORD("Now is the time",3,1) -> "Now is time" 
DELWORD("Now is the time",2,2) -> "Now time" 


7.4.27. DIGITS 


>>-DIGITS () ---------------------------------------------------- >< 


Returns the current setting of NUMERIC DIGITS. See NUMERIC for more information. 


Here is an example: 


DIGITS () -> 9 /* by default */ 


7.4.28. DIRECTORY 


»»-DIRECTORY(--4-------------- %--)----------------------------- >< 
+-newdirectory-+ 


Returns the current directory, changing it to newdirectory if an argument is supplied and the named 
directory exists. If newdirectory is not specified, the name of the current directory is returned. Otherwise, 
an attempt is made to change to the specified newdirectory. If successful, the name of the newdirectory is 
returned; if an error occurred, null is returned. 


For example, the following program fragment saves the current directory and switches to a new 
directory; it performs an operation there, and then returns to the former directory. 


/* get current directory ж/ 
curdir = directory() 
/* go play a game ж/ 
newdir = directory("/usr/games") /* Linux type subdirectory */ 
if newdir = "/usr/games" then 
do 


fortune /* tell a fortune */ 
/* return to former directory */ 
call directory curdir 
end 
else 
say "Can't find /usr/games" 


7.4.29. ENDLOCAL (Linux only) 


>>-ENDLOCAL () -------------------------------------------------- >< 
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Restores the directory and environment variables in effect before the last SETLOCAL function was run. 
If ENDLOCAL is not included in a procedure, the initial environment saved by SETLOCAL is restored 
upon exiting the procedure. 


ENDLOCAL returns a value of 1 if the initial environment is successfully restored and a value of 0 if no 
SETLOCAL was issued or the action is otherwise unsuccessful. 


Here is an example: 


n = SETLOCALO /* saves the current environment */ 
/ж 
Тһе program can now change environment variables 
(with the VALUE function) and then work in the 
changed environment. 
ж/ 
n = ENDLOCAL() /* restores the initial environment */ 


For additional examples, see SETLOCAL. 


7.4.30. ERRORTEXT 


>>-ERRORTEXT (n) ------------------------------------------------ >< 


Returns the Rexx error message associated with error number и. и must be in the range 0-99. It returns 
the null string if n is in the allowed range but is not a defined Rexx error number. See Error Numbers and 
Messages for a complete description of error numbers and messages. 


Here are some examples: 


ERRORTEXT (16) -> ыы ж жездің 
ERRORTEXT (60) E n 


7.4.31. FILESPEC 
»»-FILESPEC(option,filespec)----------------------------------- >< 

Returns a selected element of filespec, given file specification, identified by one of the following option 
strings: 

Drive 


The drive letter of the given filespec. Only available on Windows 


Path 
The directory path of the given filespec. 


Location 


The full location portion of the given filespec. On Windows, this will include both the Drive and 
Path information. On other platforms, this returns the same result as the Path option. 
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Name 


The file name of the given filespec. 


Extension 
The extension portion of the filespec file name. 


If filespec the requested information, then the FILESPEC function returns a null string (""). 


Note: Only the initial letter of option is needed. 


Here are some Windows examples: 


thisfile = "C:\WINDOWS\UTIL\SYSTEM. INI" 


say FILESPEC("drive",thisfile) /* says "C:" ж/ 
say FILESPEC("path", thisfile) /* says "\WINDOWS\UTIL\" */ 
say FILESPEC("location",thisfile) /* says "C:NWINDOWSNUTILN" */ 
say FILESPEC("name",thisfile) /* says "SYSTEM. INI" ж/ 
say FILESPEC("extension",thisfile) /* says "INI" ж/ 

part = "name" 

say FILESPEC (part ,thisfile) /* says "SYSTEM.INI" ж/ 


7.4.32. FORM 


>>-FORM () ------------------------------------------------------ >< 


Returns the current setting of NUMERIC FORM. See NUMERIC for more information. 


Here is an example: 


FORM() -> "SCIENTIFIC" /ж by default ж/ 


7.4.33. FORMAT 


>>-ЕОВМАТ (number------------------------------------------------ > 
>--%------------------------------------------------------------- +--> 
%-,--%-------- %--%------------------------------------------ +-+ 
+-before-+ +-,--+------- %--%------------------------ +-+ 
+-after-+ +-,--+------+--+-------+-+ 


%-ехрр-% +-,expt-+ 
>--)----------------------------------------------------------- >< 


Returns number, rounded and formatted. 
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The number is first rounded according to standard Rexx rules, as though the operation number+0 had 
been carried out. The result is precisely that of this operation if you specify only number. If you specify 
any other options, the number is formatted as described in the following. 


The before and after options describe how many characters are used for the integer and decimal parts of 
the result, respectively. If you omit either or both of them, the number of characters used for that part is 
as needed. 


If before is not large enough to contain the integer part of the number (plus the sign for a negative 
number), an error results. If before is larger than needed for that part, the number is padded on the left 
with blanks. If after is not the same size as the decimal part of the number, the number is rounded (or 
extended with zeros) to fit. Specifying 0 causes the number to be rounded to an integer. 


Here are some examples: 


FORMAT ("3", 4) -> y 3" 
FORMAT("1.73",4,0) => " 2" 
FORMAT("1.73",4,3) -> " 1.730" 
FORMAT("-.76",4,1) -> " -0.8" 
ЕОВМАТ("3.03",4) -> " 3.03" 
FORMAT(" - 12.73", ,4) -> "-12.7300" 
FORMAT(" - 12.73") -> "12.73" 
FORMAT ("0.000") -> "о" 


The first three arguments аге as described previously. Іп addition, expp and expt control the exponent part 
of the result, which, by default, is formatted according to the current NUMERIC settings of DIGITS and 
FORM. expp sets the number of places for the exponent part; the default is to use as many as needed 
(which can be zero). expt specifies when the exponential expression is used. The default is the current 
setting of NUMERIC DIGITS. 


If expp is 0, the number is not in exponential notation. If expp is not large enough to contain the 
exponent, an error results. 


If the number of places needed for the integer or decimal part exceeds expt or twice expt, respectively, 
the exponential notation is used. If expt is 0, the exponential notation is always used unless the exponent 
would be 0. (If expp is 0, this overrides a 0 value of expt.) If the exponent would be 0 when a nonzero 
expp is specified, then expp+2 blanks are supplied for the exponent part of the result. If the exponent 
would be 0 and expp is not specified, the number is not an exponential expression. 


Here are some examples: 


FORMAT("12345.73", , ,2,2) -> "1.234573Е+04" 
FORMAT ("12345.73", „3, ,0) -> "1.235Е+4" 

FORMAT ("1.234573", ,3, ,0) -> "1.235" 

FORMAT ("12345.73", , ,3,6) -> "12345.73" 
FORMAT("1234567e5", ,3,0) -> "123456700000.000" 


7.4.34. FUZZ 


>>-Е/72()------------------------------------------------------ >< 


Returns the current setting of NUMERIC FUZZ. See NUMERIC for more information. 
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Here is an example: 


FUZZ() -> 0 /* by default */ 


7.4.35. INSERT 


>>- INSERT (new, target--------------------------------------------— > 
>--4--------------------------------------- %--)---------------- >< 
%-,--%---%--%------------------------- +-+ 
%-п-%  -,--4--------4--4------4-* 


*t-length-* +-,рад-+ 


Inserts the string new, padded or truncated to length length, into Ше string target after the nth character. 
The default value for n is 0, which means insertion before the beginning of the string. If specified, n and 
length must be positive whole numbers or zero. If n is greater than the length of the target string, the 
string new is padded at the beginning. The default value for length is the length of new. If length is less 
than the length of the string new, then INSERT truncates new to length length. The default pad character 
is a blank. 


Here are some examples: 


INSERT(" ","abcdef",3) -> "abc def" 
INSERT ("123", "арс",5,6) -> "арс 123 E 
INSERT("123","abc",5,6,"+") => "арс++123+++" 
INSERT ("123" „"арс") -> "123abc" 
INSERT("123", "abc", ,5,"-") -> "123--abc" 


7.4.36. LASTPOS (Last Position) 


>>-LASTPOS (needle,haystack-4--------------------------- %--)---------------------- >< 
%-,--%------- %--%--------- +-+ 
*t-start-* +-,length-+ 


Returns the position of the last occurrence of one string, needle, in another, haystack. (See also POS 
(Position).) It returns 0 if needle is a null string or not found. By default, the search starts at the last 
character of haystack and scans backward to the beginning of the string. You can override this by 
specifying start, the point at which the backward scan starts and length, the range of characters to scan. 
The start must be a positive whole number and defaults to receiving string^length if larger than that 
value or omitted. The length must be a non-negative whole number and defaults to start. 


Here are some examples: 


LASTPOS(" ","abc def ghi") -> 8 
LASTPOS(" ","abcdefghi") -> 0 
LASTPOS ("xy", "efgxyz") -> 4 
LASTPOS(" ","abc def ghi",7) -> 4 
LASTPOS(" ","abc def ghi",7,3) -> 0 
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7.4.37. LEFT 


>>-LEFT (string, length--+------ %--)----------------------------- >< 
+-,pad-+ 


Returns a string of length length, containing the leftmost length characters of string. The string returned 
is padded with pad characters, or truncated, on the right as needed. The default pad character is a blank. 
length must be a positive whole number or zero. The LEFT function is exactly equivalent to: 


»»-SUBSTR(string,1,length--4------ %--)------------------------- >< 
+-,pad-+ 


Here are some examples: 


LEFT("abc d",8) -> "арса " 
LEFT("abc d",8,".") -> "abc d..." 
LEFT("abc def",7) -> "арс де" 


7.4.38. LENGTH 
»»-LENGTH(string)---------------------------------------------- >< 


Returns the length of string. 


Here are some examples: 


LENGTH ("abcdefgh") -> 8 
LENGTH("abc defg") -> 8 
LENGTH ("") -> 0 


7.4.39. LINEIN (Line Input) 


»»-LINEIN(--4------ %--%------------------------- %--)----------- >< 
%-паше-%  4-,--4------4--4--------4-- 


+-line-+ +-,count-+ 


Returns count lines read from the character input stream name. The count must be 1 or 0 (To understand 
the input and output functions, see Input and Output Streams.) If you omit name, the line is read from the 
default input stream, STDIN. The default count is 1. 


For persistent streams, a read position is maintained for each stream. Any read from the stream starts at 
the current read position by default. Under certain circumstances, a call to LINEIN returns a partial line. 
This can happen if the stream has already been read with the CHARIN function, and part but not all of a 
line (and its termination, if any) has already been read. When the language processor completes reading, 
the read position is moved to the beginning of the next line. 


A line number may be given to set the read position to the start of a specified line. This line number must 
be positive and within the bounds of the stream, and must not be specified for a transient stream. The 
read position can be set to the beginning of the stream by giving line a value of 1. 
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If you give a count of 0, then no characters are read and a null string is returned. 


For transient streams, if a complete line is not available in the stream, then execution of the program 
usually stops until the line is complete. If, however, it is impossible for a line to be completed because of 
an error or another problem, the NOTREADY condition is raised (see Errors during Input and Output) 
and LINEIN returns whatever characters are available. 


Here are some examples: 


LINEIN() /* Reads one line from the ж/ 
/ж default input stream; */ 
/* usually this is an entry ж/ 
/* typed at the keyboard */ 

myfile - "ANYFILE.TXT" 

LINEIN(myfile) -» "Current line" /* Reads one line from ж/ 
/* ANYFILE.TXT, beginning ж/ 
/ж at the current read ж/ 
/* position. (If first call, »/ 
/* file is opened and the */ 
/* first line is read.) ж/ 


LINEIN(myfile,1,1) -> "first line" /ж Opens and reads the first ж/ 
/* line of ANYFILE.TXT (if */ 
/* the file is already open, ж/ 


/* reads first line); sets */ 
/* read position on the */ 
/* second line. ж/ 
LINEIN(myfile,1,0) -> "" /* No read; opens ANYFILE.TXT */ 


/* (if file is already open, ж/ 
/* sets the read position to ж/ 


/* the first line). ж/ 
LINEIN(myfile, ,0) -> "" /* No read; opens ANYFILE.TXT */ 
/* (no action if the file is ж/ 
/* already open). */ 


LINEIN("QUEUE:") -» "Queue line" /* Read a line from the queue. */ 
/* If the queue is empty, the ж/ 
/* program waits until a line ж/ 
/* is put on the queue. ж/ 


Note: If you want to read complete lines from the default input stream, as іп a dialog with a user, use 
the PULL or PARSE PULL instruction. 


The PARSE LINEIN instruction is also useful in certain cases. (See PARSE LINEIN.) 
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7.4.40. LINEOUT (Line Output) 


»»-LINEOUT(--4------ %--%-------------------------- DA >< 


Returns 0 if successful in writing string to the character output stream name, or 1 if an error occurs while 
writing the line. (To understand the input and output functions, see Input and Output Streams.) If you 
omit string but include line, only the write position is repositioned. If string is a null string, LINEOUT 
repositions the write position (if you include line) and does a carriage return. Otherwise, the stream is 
closed. LINEOUT adds a line-feed and a carriage-return character to the end of string. 


If you omit name, the line is written to the default output stream STDOUT (usually the display). 


For persistent streams, a write position is maintained for each stream. Any write to the stream starts at 
the current write position by default. (Under certain circumstances the characters written by a call to 
LINEOUT can be added to a partial line previously written to the stream with the CHAROUT routine. 
LINEOUT stops a line at the end of each call.) When the language processor completes writing, the 
write position is set to the beginning of the line following the one just written. When the stream is first 
opened, the write position is at the end of the stream, so that calls to LINEOUT append lines to the end 
of the stream. 


You can specify a line number to set the write position to the start of a particular line in a persistent 
stream. This line number must be positive and within the bounds of the stream unless it is a binary 
stream (though it can specify the line number immediately after the end of the stream). A value of 1 for 
line refers to the first line in the stream. Note that, unlike CHAROUT, you cannot specify a position 
beyond the end of the stream for non-binary streams. 


You can omit the string for persistent streams. If you specify line, the write position is set to the start of 
the line that was given, nothing is written to the stream, and the function returns 0. If you specify neither 
line nor string, the stream is closed. Again, the function returns 0. 


Execution of the program usually stops until the output operation is effectively complete. For example, 
when data is sent to a printer, the system accepts the data and returns control to Rexx, even though the 
output data might not have been printed. Rexx considers this to be complete, even though the data has 
not been printed. If, however, it is impossible for a line to be written, the NOTREADY condition is raised 
(see Errors during Input and Output), and LINEOUT returns a result of 1, that is, the residual count of 
lines written. 


Here are some examples: 


LINEOUT(,"Display this") /* Writes string to the default ж/ 
/* output stream (usually, the ж/ 
/ж display); returns 0 if ж/ 
/* successful ж/ 


myfile = "ANYFILE.TXT" 

LINEOUT(myfile,"A new line") /* Opens the file ANYFILE.TXT and */ 
/* appends the string to the end. */ 
/* If the file is already open,  */ 
/* the string is written at the */ 
/* current write position. ж/ 
/* Returns 0 if successful. ж/ 
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LINEOUT(myfile,"A new start",1) 


LINEOUT(myfile, ,1) 


LINEOUT (myfile) 


/* 
/* 
/* 
/* 


/* 
/ж 
/ж 


/ж 


Opens the file (if not already */ 
open); overwrites first line ж/ 
with a new line. */ 
Returns 0 if successful. */ 
Opens the file (if not already */ 
open). No write; sets write ж/ 
position at first character. ж/ 
Closes ANYFILE.TXT ж/ 
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LINEOUT is often most useful when called as a subroutine. The return value is then available in the 


variable RESULT. For example: 


Call LINEOUT "A:rexx.bat","Shell",1 


Call LINEOUT ,"Hello" 


Note: If the lines are to be written to the default output stream without the possibility of error, use the 


SAY instruction instead. 


7.4.41. LINES (Lines Remaining) 


+-, Normal-+ 
»»-LINES(--4------ *----- %---------- %---)----------------------- >< 
+-паше-+ +-, Count--+ 


Returns 1 if any data remains between Ше current read position and Ше end of Ше character input stream 
name. It returns 0 if no data remains. In effect, LINES reports whether a read action that CHARIN (see 
CHARIN (Character Input)) or LINEIN (see LINEIN (Line Input)) performs will succeed. (To 
understand the input and output functions, see Input and Output Streams.) 


The ANSI Standard has extended this function to allow an option: "Count". If this option is used, LINES 
returns the actual number of complete lines remaining in the stream, irrespective of how long this 


operation takes. 


The option "Normal" returns 1 if there is at least one complete line remaining in the file or 0 if no lines 


remain. 
The default is "Normal". 


Here are some examples: 


LINES (myfile) -> 0 
LINES О -> 1 


/ж 
/ж 
/ж 
/ж 


at end of the file ж/ 
data remains іп the ж/ 


default input stream */ 


STDIN: 


ж/ 


Note: The CHARS function returns the number of characters іп a persistent stream or the presence 
of data in a transient stream. 
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7.4.42. LOWER 


»»-LOWER(string-4---------------------------- e >< 
%--,--%----- %--%----------- +-+ 
*--n--* +--,length--+ 


Returns a new string with Ше characters of string beginning with character n for length characters 
converted to lowercase. If n is specified, it must be a positive whole number. If n is not specified, the case 
conversion will start with the first character. If length is specified, it must be a non-negative whole 
number. If length the default is to convert the remainder of the string. 


Examples: 

lower("Albert Einstein") -> "albert einstein" 
lower ("ABCDEF", 4) -> "ABCdef" 
lower("ABCDEF", 3, 2) -> "ABcdEF" 


7.4.43. MAX (Maximum) 


V | 
»»-MAX(----number-4--)----------------------------------------- >< 


Returns the largest number of the list specified, formatted according to the current NUMERIC settings. 
You can specify any number of numbers. 


Here are some examples: 


MAX(12,6,7,9) -> 12 
МАХ(17.3,19,17.03) -> 19 
МАХ(-7,-3,-4.3) -> -3 


MAX(1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21) => 21 


7.4.44. MIN (Minimum) 


V | 
»»-MIN(----number-4--)----------------------------------------- >< 


Returns the smallest number of the list specified, formatted according to the current NUMERIC settings. 
You can specify any number of numbers. 


Here are some examples: 


MIN(12,6,7,9) -> 6 
МІМ(17.3,19,17.03) -> 17.03 
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MIN(-7,-3,-4.3) -> -7 
MIN(21,20,19,18,17,16,15,14,13,12,11,10,9,8,7,6,5,4,3,2,1) -> 1 


7.4.45. OVERLAY 


>>-OVERLAY (new,target------------------------------------------- > 
>--%--------------------------------------- ж--)---------------- >< 
%-,--%---%--%------------------------- +-+ 
%-п-%  -,--4--------4--4------4-* 


+-length-+ +-,рад-+ 


Returns Ше string target, which, starting at Ше nth character, is overlaid with the string new, padded or 
truncated to length length. The overlay may extend beyond the end of the original target string. If you 
specify length, it must be a positive whole number or zero. The default value for length is the length of 
new. If n is greater than the length of the target string, the string new is padded at the beginning. The 
default pad character is a blank, and the default value for n is 1. If you specify n, it must be a positive 
whole number. 


Here are some examples: 


OVERLAY(" ","abcdef",3) -> "аһ def" 
OVERLAY(".", "abcdef",3,2) -> "ab. ef" 
OVERLAY ("qq" , "abcd") ->  "qqcd" 
OVERLAY ("qq" , "abcd" ,4) ->  "abcqq" 
OVERLAY("123","abc",5,6,"4") -> “abc+123+++" 


7.4.46. POS (Position) 


>>-POS (needle,haystack--4--------------------------- %--)-------------------------- >< 
%-,--%------- %--%--------- +-+ 


+-start-+ +-,length-+ 


Returns the position of one string, needle, in another, haystack. (See also LASTPOS (Last Position).) It 
returns 0 if needle is a null string or not found or if start is greater than the length of haystack. By 
default, the search starts at the first character of the receiving string (that is, the value of start is 1), and 
continues to the end of the string. You can override this by specifying start, the point at which the search 
starts, and length, the bounding limit for the search. If specified, start must be a positive whole number 
and length must be a non-negative whole number. 


Here are some examples: 


POS("day", "Saturday") -> 6 
POS("x","abc def ghi") -> 0 
POS(" ","abc def ghi") -> 4 
POS(" ","abc def ghi",5) -> 8 
POS(" ","abc def ghi",5,3) -> 0 
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7.4.47. QUALIFY 


>>- QUALIFY (name) ----------------------------------------------- >< 


Returns the a fully qualified file name for name. Qualifying merely expands the file name into a name 
that includes directory information. The file does not need to exist to generate the full name. 


7.4.48. QUEUED 


>>-QUEUED () ---------------------------------------------------- >< 


Returns the number of lines remaining in the external data queue when the function is called. (See Input 
and Output Streams for a discussion of Rexx input and output.) 


Here is an example: 


QUEUED () -» 5 /* Perhaps */ 


7.4.49. RANDOM 


»»-RANDOM(--4------------------------------------ %--)---------- >< 
Ee e + 
+-+-------- 4-,-4------- %--%-------- +-+ 
%--шіп--% %--пах--% +--,seed-+ 


Returns а quasi-random whole number іп the range min to max inclusive. If you specify max ог min,max, 
then max minus min cannot exceed 999999999, min and max default to 0 and 999, respectively. To start a 
repeatable sequence of results, use a specific seed as the third argument, as described in Note 1. This 
seed must be a positive whole number from 0 to 999999999, 


Here are some examples: 


RANDOM () -> 305 

RANDOM(5,8) -> 7 

RANDOM (2) -> 0 /* 0 to 2 ж/ 
RANDOM(, ,1983) -> 123 /ж reproducible */ 
RANDOM(-5, 5) -> -3 

Notes: 


1. To obtain a predictable sequence of quasi-random numbers, use RANDOM a number of times, but 
specify a seed only the first time. For example, to simulate 40 throws of a 6-sided, unbiased die: 


RAND0M(1,6,12345) /ж any number would */ 
/* do for a seed ж/ 


sequence 


do 39 

sequence = sequence RANDOM(1,6) 
end 

say sequence 
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The numbers are generated mathematically, using the initial seed, so that as far as possible they 
appear to be random. Running the program again produces the same sequence; using a different 
initial seed almost certainly produces a different sequence. If you do not supply a seed, the first time 
RANDOM is called, an arbitrary seed is used. Hence, your program usually gives different results 
each time it is run. 


2. The random number generator is global for an entire program; the current seed is not saved across 
internal routine calls. 


7.4.50. REVERSE 


>>-REVERSE (string) --------------------------------------------- >< 


Returns string reversed. 


Here are some examples: 


REVERSE ("АВс.") -> ".cBA" 
REVERSE("XYZ ") -> " ZYX" 


7.4.51. RIGHT 


>>-RIGHT (string, length--+------ Е) a A EE >< 
+-,pad-+ 


Returns a string of length length containing the rightmost length characters of string. The string returned 
is padded with pad character, or truncated, on the left as needed. The default pad character is a blank. 
The /ength must be a positive whole number or zero. 


Here are some examples: 


RIGHT("abc а",8) -> " abc d" 
RIGHT("abc def",5) -> "с def" 
RIGHT("12",5,"0") -> "00012" 


7.4.52. RXFUNCADD 


>>-RXFUNCADD (пате, module-4------------ a E >< 
+- „ргоседиге-+ 


Registers the function , making it available to Rexx procedures. The module is Ше name of an external 
library where the native function is located. In some environments, such as Unix-based systems, the 
library name is case sensitive. The procedure is the name of the exported prodcure inside of module. If 
procedure is not specified, it defaults to name. The procedure is generally case-sensitive. RxFuncAdd 
will attempt to resolve the procedure address using the name as specified and if that attempt fails, will 
retry using an uppercased name. 
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A return value 0 signifies successful registration and that the registered function has been located in the 
specified module. A return value 1 signifies that the function could not be resolved. 


rxfuncadd("SysCls","rexxutil", "SysCls") -> 0 /* if SysCls can be located */ 
-» 1 /* if SysCls can not be located */ 


7.4.53. RXFUNCDROP 


>>-RXFUNCDROP (name) -------------------------------------------- >< 


Removes (deregisters) the function name from the list of available functions. A zero return value 
signifies successful removal. 


rxfuncdrop("SysLoadFuncs") -> 0 /* if successfully removed */ 


7.4.54. RXFUNCQUERY 


>>-RXFUNCQUERY (name) ------------------------------------------- >< 


Queries the list of available functions for the function name. It returns a value of 0 if the function is 
registered, and a value of 1 if it is not. 


rxfuncquery ("SysLoadFuncs" ) -» 0 /* if registered ж/ 


7.4.55. RXQUEUE 


»»-RXQUEUE (-+-"Create"-+------------ +-+-)---------------------- >< 
| +-,queuename-+ | 


*-"Delete",queuename------ * 
T-"Get'"------------------- + 
*-"Set",newqueuename------ * 


Creates and deletes external data queues. It also sets and queries their names. 


"Create" 


creates a queue with the name queuename if you specify queuename and if no queue of that name 
exists already. You must not use SESSION as a queuename. If you specify no queuename, then the 
language processor provides a name. The name of the queue is returned in either case. 


The maximum length of queuename can be 1024 characters. 


Many queues can exist at the same time, and most systems have sufficient resources available to 
support several hundred queues at a time. If a queue with the specified name exists already, a queue 
is still created with a name assigned by the language processor. The assigned name is then returned 
to you. 
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"Delete" 


deletes the named queue. It returns 0 if successful or a nonzero number if an error occurs. Possible 
return values are: 


0 

Queue has been deleted. 
5 

Not a valid queue name or tried to delete queue named "SESSION". 
9 

Specified queue does not exist. 
10 

Queue is busy; wait is active. 
12 

A memory failure has occurred. 
1002 


Failure in memory manager. 


"Get" 


returns the name of the queue currently in use. 


"Set" 
sets the name of the current queue to newqueuename and returns the previously active queue name. 


The first parameter determines the function. Only the first character of the first parameter is significant. 
The parameter can be entered in any case. The syntax for a valid queue name is the same as for a valid 
Rexx symbol. 


The second parameter specified for Create, Set, and Delete must follow the same syntax rules as the 
Rexx variable names. There is no connection, however, between queue names and variable names. A 
program can have a variable and a queue with the same name. The actual name of the queue is the 
uppercase value of the name requested. 


Named queues prevent different Rexx programs that are running in a single session from interfering with 
each other. They allow Rexx programs running in different sessions to synchronize execution and pass 
data. LINEIN("QUEUE:") is especially useful because the calling program stops running until another 
program places a line on the queue. 


/* default queue ж/ 
rxqueue ("Get") -» "SESSION" 

/* assuming FRED does not already exist */ 
rxqueue("Create", "Fred") -> "FRED" 

/* assuming SESSION had been active */ 
rxqueue("Set", "Fred") -» "SESSION" 
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/* assuming FRED exists ж/ 
rxqueue("delete", "Fred") -> "0" 


7.4.56. SETLOCAL (Linux only) 


>>-SETLOCAL () -------------------------------------------------- >< 


Saves the current working directory and the current values of the environment variables that are local to 
the current process. 


For example, SETLOCAL can be used to save the current environment before changing selected settings 
with the VALUE function (see VALUE. To restore the directory and environment, use the ENDLOCAL 
function (see ENDLOCAL. 


SETLOCAL returns a value of 1 if the initial directory and environment are successfully saved and a 
value of 0 if unsuccessful. If SETLOCAL is not followed by an ENDLOCAL function in a procedure, 
the initial environment saved by SETLOCAL is restored upon exiting the procedure. 


Here is an example: 


/* Current path is "user/bin" */ 

n = SETLOCAL() /* saves all environment settings */ 
/* Now use the VALUE function to change the PATH variable */ 
p = VALUE("Path","home/user/bin". "ENVIRONMENT" ) 

/* Programs in directory home/user/bin can now be run */ 


n = ENDLOCAL() /* restores initial environment including */ 
/* the changed PATH variable, which is ж/ 
/* "user/bin" ж/ 


7.4.57. SIGN 


>>-SIGN (number)------------------------------------------------ >< 


Returns a number that indicates the sign of number. The number is first rounded according to standard 
Rexx rules, as though the operation number+0 had been carried out. It returns -1 if number is less than 0, 
0 if it is 0, and 1 if it is greater than 0. 


Here are some examples: 


SIGN("12.3") -> 1 
SIGN(" -0.307") -> =] 
SIGN(0.0) => 0 


7.4.58. SOURCELINE 


>>-SOURCELINE (--+---+--) --------------------------------------- >< 
T-n-t 
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Returns the line number of the final line in the program if you omit n. If you specify n, returns the nth 
line in the program if available at the time of execution. Otherwise, it returns a null string. If specified, п 
must be a positive whole number and must not exceed the number that a call to SOURCELINE with no 
arguments returns. 


If the Rexx program is in tokenized form the this function raises an error for all attempts to retrieve a line 
of the program. 


Here are some examples: 


SOURCELINE () -> 10 
SOURCELINE(1) -> "/* This is a 10-line Rexx program */" 


7.4.59. SPACE 


»»-SPACE(string--4-------------------- %--)--------------------- >< 
+- --+---+--+------+-+ 
%-п-% +-,рад-+ 


Returns Ше whitespace-delimited words in string with n pad characters between each word. If you 
specify n, it must be a positive whole number or zero. If it is 0, all whitespace characters are removed. 
Leading and trailing whitespace characters are always removed. The default for п is 1, and the default 
pad character is a blank. 


Here are some examples: 


SPACE("abc def ") -> "арс def" 
SPACE(" abc def",3) -> "abc def" 
SPACE("abc def ",1) -> "арс def" 
SPACE("abc def ",0) -> "abcdef" 
SPACE("abc def ",2,"+") -> парс++дет" 


7.4.60. STREAM 


>>-STREAM (name--4----------------------------------- %--)------- >< 
| *-State---------------------- * | 
%-,--%---------------------------- +-+ 
+-Command-- ,--stream_command-+ 
*-Description---------------- * 


Returns a string describing the state of, or the result of an operation upon, the character stream name. 
The result may depend on characteristics of the stream that you have specified in other uses of the 
STREAM function. (To understand the input and output functions, see Input and Output Streams.) This 
function requests information on the state of an input or output stream or carries out some specific 
operation on the stream. 


The first argument, name, specifies the stream to be accessed. The second argument can be one of the 
following strings that describe the action to be carried out. (Only the capitalized letter is needed; all 
characters following it are ignored.) 
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Command 


an operation (specified by the stream_command given as the third argument) is applied to the 
selected input or output stream. The string that is returned depends on the command performed and 
can be a null string. The possible input strings for the stream_command argument are described 
later. 


Description 
returns any descriptive string associated with the current state of the specified stream. It is identical 
to the State operation, except that the returned string is followed by a colon and, if available, 
additional information about the ERROR or NOTREADY states. 

State 
returns a string that indicates the current state of the specified stream. This is the default operation. 


The returned strings are as described in STATE. 


Note: The state (and operation) of an input or output stream is global to a Rexx program; it is not 
saved and restored across internal function and subroutine calls (including those calls that a CALL 
ON condition trap causes). 


7.4.60.1. Stream Commands 


The following stream commands are used to: 


* Open a stream for reading, writing, or both. 

* Close a stream at the end of an operation. 

* Position the read or write position within a persistent stream (for example, a file). 
* Get information about a stream (its existence, size, and last edit date). 


The streamcommand argument must be used when--and only when--you select the operation C 
(command). The syntax is: 


>>-5ТВЕАМ (пате, "C" , streamcommand) ------------------------------ >< 


In this form, the STREAM function itself returns a string corresponding to the given streamcommand if 
the command is successful. If the command is unsuccessful, STREAM returns an error message string in 
the same form as the D (Description) operation supplies. 


For most error conditions, the additional information is in the form of a numeric return code. This return 
code is the value of ERRNO that is set whenever one of the file system primitives returns with a -1. 


7.4.60.1.1. Command Strings 


The argument streamcommand can be any expression that the language processor evaluates to a 
command string that corresponds to the following diagram: 


+-BOTH--| Write Options |--+ 
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>>-%-ОРЕМ----------------------------- %--%------------- +-+----- >< 
| *-READ--------------------- + +-| Options |-+ | 
| +-WRITE--| Write Options |-+ 
*-CLOSE----------------------------------------------- * 
*-FLUSH----------------------------------------------- * 
| +- = -+ +-CHAR-+ | 
%-%-5ЕЕК----- %--%----- +-offset--+------- %--%------ %---% 
| +-POSITION-+ +- < -+ +-READ--+  *-LINE-* | 
| +- + -+ +-WRITE-+ | 
| тезите | 
+-QUERY--+-DATETIME-------------------------- %-------- + 
*-EXISTS---------------------------- * 
*-HANDLE---------------------------- * 
| +-CHAR-+ | 
+-+-SEEK-----+--+-READ--+------+--+-+ 
| +-POSITION-+ | +-LINE-+ | | 
| | +-CHAR-+ | | 
| +-WRITE--+------ +-+ | 
| | +-LINE-+ | | 
| %-5Ү5------------- + | 
%-8І2Е------------------------------ + 
*-STREAMTYPE------------------------ * 
*-TIMESTAMP------------------------- * 
Write Options: 
|--%--------- %-------------------------------------------------- 
+-APPEND--+ 
+-REPLACE-+ 
Options: 
%----------------------------------- + 
V | 
|--%------------ *----t-NOBUFFER---------------------- %-%-------- 
*-SHARED- ---- * +ЕВІЛАҚҮ-=+-======---====-=-=5 ФЕ 
+-SHAREREAD--+ +-RECLENGTH--length-+ 


+-SHAREWRITE-+ 


OPEN 


opens the named stream. The default for OPEN is to open the stream for both reading and writing 
data, for example, "OPEN BOTH". 


The STREAM function itself returns a description string similar to the one that the D option 
provides, for example, "READY:" if the named stream is successfully opened, or "ERROR:2" if the 
named stream is not found. 


The following is a description of the options for OPEN: 


READ 


opens the stream for reading only. 


ooRexx Reference Version 4.0.0 413 


Chapter 7. Functions 


WRITE 


opens the stream for writing only. 


BOTH 
opens the stream for both reading and writing. (This is the default.) Separate read and write 
pointers are maintained. 

APPEND 
positions the write pointer at the end of the stream. The write pointer cannot be moved 
anywhere within the extent of the file as it existed when the file was opened. 

REPLACE 
sets the write pointer to the beginning of the stream and truncates the file. In other words, this 
option deletes all data that was in the stream when opened. 

SHARED 


Enables another process to work with the stream in a shared mode. This mode must be 
compatible with the shared mode (SHARED, SHAREREAD, or SHAREWRITE) used by the 
process that opened the stream. 


SHAREREAD 


Enables another process to read the stream in a shared mode. 


SHAREWRITE 


Enables another process to write the stream in a shared mode. 


NOBUFFER 


turns off buffering of the stream. Thus, all data written to the stream is flushed immediately to 
the operating system for writing. This option can severely affect output performance. 
Therefore, use it only when data integrity is a concern, or to force interleaved output to a 
stream to appear in the exact order in which it was written. 


BINARY 


causes the stream to be opened in binary mode. This means that line end characters are ignored 
and treated as another byte of data. This is intended to force file operations that are compatible 
with other Rexx language processors that run on record-based systems, or to process binary 
data using the line operations. 


Note: Specifying the BINARY option for a stream that does not exist but is opened for writing 
also requires the RECLENGTH option to be specified. Omitting the RECLENGTH option in 
this case raises an error condition. 
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RECLENGTH length 


allows the specification of an exact length for each line in a stream. This allows line operations 
on binary-mode streams to operate on individual fixed-length records. Without this option, line 
operations on binary-mode files operate on the entire file (for example, as if the RECLENGTH 
option were specified with a length equal to that of the file). length must be 1 or greater. 


Examples: 


stream(strout,"c","open") 
stream(strout,"c","open write") 
stream(strinp,"c","open read") 
stream(strinp,"c","open read shared") 


CLOSE 


closes the named stream. The STREAM function itself returns READY: if the named stream is 


successfully closed, or an appropriate error message. If an attempt is made to close an unopened 
file, STREAM returns a null string (""). 


Example: 


stream("STRM.TXT","c","close") 


FLUSH 


forces any data currently buffered for writing to be written to this stream. 


SEEK offset 


sets the read or write position within a persistent stream. If the stream is opened for both reading 
and writing and no SEEK option is specified, both the read and write positions are set. 


Note: See Input and Output Streams for a discussion of read and write positions in a persistent 
stream. 


To use this command, the named stream must first be opened with the OPEN stream command or 
implicitly with an input or output operation. One of the following characters can precede the offset 
number: 


explicitly specifies the offset from the beginning of the stream. This is the default if no prefix is 
supplied. Line Offset-1 means the beginning of stream. 


specifies offset from the end of the stream. 


specifies offset forward from the current read or write position. 
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specifies offset backward from the current read or write position. 


The STREAM function itself returns the new position in the stream if the read or write position is 
successfully located or an appropriate error message otherwise. 


The following is a description of the options for SEEK: 


READ 


specifies that the read position is to be set by this command. 


WRITE 


specifies that the write position is to be set by this command. 


CHAR 


specifies that the positioning is to be done in terms of characters. This is the default. 


LINE 


specifies that the positioning is to be done in terms of lines. For non-binary streams, this is an 
operation that can take a long time to complete, because, in most cases, the file must be 
scanned from the top to count line-end characters. However, for binary streams with a specified 
record length, this results in a simple multiplication of the new resulting line number by the 
record length, and then a simple character positioning. See Line versus Character Positioning 
for a detailed discussion of this issue. 


Note: If you do line positioning in a file open only for writing, you receive an error message. 


Examples: 


stream(name,"c","seek =2 read") 
stream(name,"c","seek +15 read") 
stream(name,"c","seek -7 write line") 
fromend = 125 

stream(name,"c","seek <"fromend read) 


POSITION 
is a synonym for SEEK. 


7.4.60.1.2. QUERY Stream Commands 


Used with these stream commands, the STREAM function returns specific information about a stream. 
Except for QUERY HANDLE and QUERY POSITION, the language processor returns the query 
information even if the stream is not open. The language processor returns UNKNOWN for QUERY 
STREAMTYPE and the null string for nonexistent streams. 


Note that technically although a directory is persistent, it is not a stream. If the directory exists, the date / 
time queries return the time stamp of the directory, QUERY SIZE returns 0, and QUERY 
STREAMTYPE returns UNKNOWN. The other commands return the null string. 
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QUERY DATETIME 


returns the date and time stamps of a stream in US format. This is included for compatibility with 
OS/2®. 


stream("..\file.txt","c","query datetime") 
A sample output might be: 
11-12-98 03:29:12 
QUERY EXISTS 
returns the full path specification of the named stream, if it exists, or a null string. 
stream("..\file.txt","c","query exists") 
A sample output might be: 
c:\data\file.txt 
QUERY HANDLE 


returns the handle associated with the open stream. 
stream("..\file.txt","c","query handle") 


A sample output might be: 
3 


QUERY POSITION 


returns the current read or write position for the stream, as qualified by the following options: 


READ 
returns the current read position. 


WRITE 


returns the current write position. 


Note: If the stream is open for both reading and writing, the default is to return the read 
position. Otherwise, it returns the appropriate position by default. 


CHAR 


returns the position in terms of characters. This is the default. 


LINE 


returns the position in terms of lines. For non-binary streams, this operation can take a long 
time to complete, because the language processor starts tracking the current line number if not 
already doing so. Thus, it might require a scan of the stream from the top to count line-end 
characters. See Line versus Character Positioning for a detailed discussion of this issue. 


stream("myfile","c","query position write") 
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A sample output might be: 
247 


SYS 


returns the operating-system stream position in terms of characters. 


QUERY SIZE 


returns the size, in bytes, of a persistent stream. 
stream("..\file.txt","c","query size") 
A sample output might be: 

1305 


QUERY STREAMTYPE 


returns a string indicating whether the stream is PERSISTENT, TRANSIENT, or UNKNOWN. 


QUERY TIMESTAMP 


returns the date and time stamps of a stream in an international format. This is the preferred method 
of getting the date and time because it provides the full 4-digit year. 


stream("..\file.txt","c","query timestamp") 


A sample output might be: 
1998-11-12 03:29:12 


7.4.61. STRIP 


»»-STRIP(string--*-------------------------- %--)--------------- >< 
%-,--%-------- %--%------- +-+ 


, 


*t-option-* +-,char-+ 


Returns string with leading characters, trailing characters, or both, removed, based on the option you 
specify. The following are valid options. (Only the capitalized letter is needed; all characters following it 
are ignored.) 


Both 
removes both leading and trailing characters from string. This is the default. 


Leading 


removes leading characters from string. 


Trailing 


removes trailing characters from string. 
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The third argument, char, specifies the character to be removed, and the default is to remove all 
whitespace characters. If you specify char, it must be exactly one character long. 


Here are some examples: 


STRIP(" abc ") -> "ab c" 
STRIP(" abc ","L") -> "abc " 
STRIP(" abc ","t") -> " abc" 
STRIP("12.7000", ,0) -> "12. 7" 
STRIP("0012.700", ,0) -> "12.7" 


7.4.62. SUBSTR (Substring) 


»»-SUBSTR(string,n--4------------------------- %--)------------- >< 
%-,--%--------%--%------%-% 


+-length-+ +-,рад-+ 


Returns the substring of string that begins at the nth character and is of length length, padded with pad if 
necessary. n must be a positive whole number. If n is greater than LENGTH (string), only pad characters 
are returned. 


If you omit length, the rest of the string is returned. The default pad character is a blank. 


Here are some examples: 


SUBSTR("abc",2) -> "be" 
SUBSTR("abc",2,4) -> "bc " 
SUBSTR("abc",2,6,".") -> "bc...." 


Note: In some situations the positional (numeric) patterns of parsing templates are more convenient 
for selecting substrings, especially if more than one substring is to be extracted from a string. See 
also LEFT and RIGHT. 


7.4.63. SUBWORD 


»»-SUBWORD(string,n--4--------- %--)---------------------------- >< 
+-,length-+ 


Returns the substring of string that starts at the nth word, and is up to length whitespace-delimited words. 
n must be a positive whole number. If you omit /ength, it defaults to the number of remaining words in 
string. The returned string never has leading or trailing whitespace, but includes all whitespace 
characters between the selected words. 


Here are some examples: 


SUBWORD("Now is the time",2,2) -> "is the" 
SUBWORD("Now is the time",3) -> "the time" 
SUBWORD("Now is the time",5) -> Hn 
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7.4.64. SYMBOL 


>>-SYMBOL (name) ------------------------------------------------ >< 


Returns the state of the symbol named by name. It returns BAD if name is not a valid Rexx symbol. It 
returns VAR if it is the name of a variable, that is, a symbol that has been assigned a value. Otherwise, it 
returns LIT, indicating that it is either a constant symbol or a symbol that has not yet been assigned a 
value, that is, a literal. 


As with symbols in Rexx expressions, lowercase characters in name are translated to uppercase and 
substitution in a compound name occurs if possible. 


Note: You should specify name as a literal string, or it should be derived from an expression, to 


prevent substitution before it is passed to the function. 


Here are some examples: 


/* following: Drop А.З; J=3 */ 


SYMBOL ("J") -> "VAR" 

SYMBOL (J) -> "LIT" /* has tested "3" */ 
SYMBOL ("a.j") -> "LIT" /* has tested А.З */ 
SYMBOL (2) -> "ІІТ" /* a constant symbol ж/ 
SYMBOL ("ж") -> "BAD" /* not a valid symbol */ 


7.4.65. TIME 


»»-TIME(--4----------------------------------- %--)------------- >< 
+-оръноп--#+-------------+--<--< + +-+ 
*t-,string--*---------- +-+ 
+-,option2-+ 


Returns the local time in the 24-hour clock format hh:mm:ss (hours, minutes, and seconds) by default, 
for example, 04:41:37. 


You can use the following options to obtain alternative formats, or to gain access to the elapsed-time 
clock. (Only the capitalized letter is needed; all characters following it are ignored.) 


Civil 
returns the time in Civil format hh:mmxx. The hours can take the values 1 through 12, and the 
minutes the values 00 through 59. The minutes are followed immediately by the letters am or pm. 
This distinguishes times in the morning (12 midnight through 11:59 a.m.--appearing as 12:00am 
through 11:59am) from noon and afternoon (12 noon through 11:59 p.m.--appearing as 12:00pm 
through 11:59pm). The hour has no leading zero. The minute field shows the current minute (rather 
than the nearest minute) for consistency with other TIME results. 


Elapsed 


returns sssssssss.uuuuuu, the number of seconds and microseconds since the elapsed-time clock 
(described later) was started or reset. The returned number has no leading zeros or whitespace, and 
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the setting of NUMERIC DIGITS does not affect it. The number has always four trailing zeros in 
the decimal portion. 


The language processor calculates elapsed time by subtracting the time at which the elapsed-time 
clock was started or reset from the current time. It is possible to change the system time clock while 
the system is running. This means that the calculated elapsed time value might not be a true elapsed 
time. If the time is changed so that the system time is earlier than when the Rexx elapsed-time clock 
was started (so that the elapsed time would appear negative), the language processor raises an error 
and disables the elapsed-time clock. To restart the elapsed-time clock, trap the error through 
SIGNAL ON SYNTAX. 


The clock can also be changed by programs on the system. Many LAN-attached programs 
synchronize the system time clock with the system time clock of the server during startup. This 
causes the Rexx elapsed time function to be unreliable during LAN initialization. 


Full 


returns the number of microseconds since 00:00:00.000000 on 1 January 0001, in the format: 
dddddddddddddddddd (no leading zeros or whitespace). 


Notes: The base date of 1 January 0001 is determined by extending the current Gregorian 
calendar backward (365 days each year, with an extra day every year that is divisible by 4 
except century years that are not divisible by 400. It does not take into account any errors in the 
calendar system that created the Gregorian calendar originally. 


The value returned by Time(’F’) can be used to calculate the interval between any two times. 
Note, however, that values returned generally contain more digits that the default NUMERIC 
DIGITS setting. The NUMERIC DIGITS setting should be increased to a minimum value of 18 
when performing timestamp arithmetic. 


Hours 
returns up to two characters giving the number of hours since midnight in the format hh (no leading 
zeros or whitespace, except for a result of 0). 

Long 


returns time in the format hh:mm:ss.uuuuuu (where uuuuuu are microseconds). 


Minutes 
returns up to four characters giving the number of minutes since midnight in the format mmmm (no 
leading zeros or whitespace, except for a result of 0). 

Normal 


returns the time in the default format hh:mm:ss. The hours can have the values 00 through 23, and 
minutes and seconds, 00 through 59. There are always two digits. Any fractions of seconds are 
ignored (times are never rounded). This is the default. 
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Offset 


returns the offset of the local time from UTC in microseconds. The offset value will be negative for 
timezones west of the Prime Meridian and positive for timezones east of Prime Meridian. The local 
time( Е”) value can be converted to UTC by adding the time(’O’) value. 


Reset 


returns sssssssss.uuuuuu, the number of seconds and microseconds since the elapsed-time clock 
(described later) was started or reset and also resets the elapsed-time clock to zero. The returned 
number has no leading zeros or whitespace, and the setting of NUMERIC DIGITS does not affect 
it. The number always has four trailing zeros in the decimal portion. 


See the Elapsed option for more information on resetting the system time clock. 


Seconds 


returns up to five characters giving the number of seconds since midnight in the format sssss (no 
leading zeros or whitespace, except for a result of 0). 


Ticks 


returns the number of seconds since 00:00:00.000000 on 1 January 1970, in the format: 
dddddddddddd (no leading zeros or whitespace). 


Notes: The base date of 1 January 1970 is determined by extending the current Gregorian 
calendar backward (365 days each year, with an extra day every year that is divisible by 4 
except century years that are not divisible by 400. It does not take into account any errors in the 
calendar system that created the Gregorian calendar originally. 


The value returned by Time(’T’) can be used to calculate the interval between any two times. 
Note, however, that values returned generally contain more digits that the default NUMERIC 
DIGITS setting. The NUMERIC DIGITS setting should be increased to a minimum value of 12 
when performing timestamp arithmetic. 


Time(’T’) will return a negative number for dates prior to 1 January 1970. 


Here are some examples, assuming that the time is 4:54 p.m.: 


TIMEO 

TIME("C") 
TIME("H") 
TIME("L") 
TIME("M") 
TIME("N") 
TIME("S") 


"16:54:22" 

"4:54pm" 

"16" 

"16:54:22.120000" /* Perhaps */ 
"1014" /* 54 + 60ж16 */ 
"16:54:22" 

"60862" /ж 22 + 60*(54+60*16) ж/ 


The elapsed-time clock: 


You can use the TIME function to measure real (elapsed) time intervals. On the first call in a program to 
TIME("E") or TIME("R"), the elapsed-time clock is started, and either call returns 0. From then on, calls to 
TIME("E") and TIME("R") return the elapsed time since that first call or since the last call to TIME("R"). 
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The clock is saved across internal routine calls, which means that an internal routine inherits the time 
clock that its caller started. Any timing the caller is doing is not affected, even if an internal routine resets 
the clock. An example of the elapsed-time clock: 


time("E") -> 0 /ж Тһе first call */ 
/* pause of one second here */ 
time("E") -> 1.020000 /ж or thereabouts */ 
/* pause of one second here */ 
time("R") -> 2.030000 /ж or thereabouts */ 
/* pause of one second here */ 
time("R") -> 1.050000 /ж or thereabouts */ 


Note: The elapsed-time clock is synchronized with the other calls to TIME and DATE, so several 
calls to the elapsed-time clock in a single clause always return the same result. For this reason, the 
interval between two usual TIME/DATE results can be calculated exactly using the elapsed-time 
clock. 


If you specify string, TIME returns the time corresponding to string in the format option. The string 
must be supplied in the format option2. The default for option2 is "N". So you need to specify option2 
only if string is not in the Normal format. option2 must specify the current time, for example, not "E" or 
"К". Неге are some examples: 


time("C","11:27:21") -> 11:27am 
time("N","11:27am","C") -> 11:27:00 
time("N", "63326132161828000", "F") -> 08:16:01 


You can determine the difference between two times; for example: 


If TIME("M","5:00pm","C")-TIME("M") <=0 
then say "Time to go home" 
else say "Keep working" 


The TIME returned is the earliest time consistent with string. For example, if the result requires 
components that are not specified in the source format, then those components of the result are zero. If 
the source has components that the result does not need, then those components of the source are ignored. 


When requesting times be converted to Full or Ticks format, a date value of 1 January 0001 is used for 
the conversion. A time stamp for a time and date combination can be created by combining a value from 
Date( F) for the time of day. 


numeric digits 18 -- needed to add the timestamps 
timestamp = date(’f, ?20072301?, ^S?) + time(’f’, 708:14:22^, ^N?) 


Implementation maximum: If the number of seconds in the elapsed time exceeds nine digits 
(equivalent to over 31.6 years), an error results. 


7.4.66. TRACE 


>>-ТВАСЕ(--+-------- %--)--------------------------------------- >< 
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Returns trace actions currently in effect and, optionally, alters the setting. 


If you specify option, it selects the trace setting. It must be the valid prefix ?, one of the alphabetic 
character options associated with the TRACE instruction (that is, starting with A, C, E, F, I, L, N, 0, or R), 
or both. (See the TRACE instruction in Alphabetic Character (Word) Options for full details.) 


Unlike the TRACE instruction, the TRACE function alters the trace action even if interactive debugging 
is active. Also unlike the TRACE instruction, option cannot be a number. 


Here are some examples: 
TRACE() -> "?R" /* maybe */ 


TRACE("0") ->  "?R" /* also sets tracing off */ 
TRACE("?7I") -> "0" /ж now in interactive debugging */ 


7.4.67. TRANSLATE 


»»-TRANSLATE(string--------------------------------------------- ? 

P E )-------------------------------- +->< 
+- --+-------- +--+------------------------- +-+ +------------------------- +-)-+ 
+-tableo-+ +-,--+--------+--+------+-+ +- --+-----+--+---------+-+ 

+-tablei-+ +-,рад-+ %-ров-% +-,length-+ 


Returns string with each character translated to another character or unchanged. You can also use this 
function to reorder the characters in string. 


The output table is tableo and the input translation table is tablei. TRANSLATE searches tablei for each 
character in string. If the character is found, the corresponding character in tableo is used in the result 
string; if there are duplicates in tablei, the first (leftmost) occurrence is used. If the character is not 
found, the original character in string is used. The result string is always the same length as string. 


The tables can be of any length. If you specify neither table and omit pad, string is simply translated to 
uppercase (that is, lowercase a-z to uppercase A-Z), but, if you include pad, the language processor 
translates the entire string to pad characters. tablei defaults to XRANGE("00"x , "FF"x), and tableo defaults 
to the null string and is padded with pad or truncated as necessary. The default pad is a blank. 


pos is the position of the first character of the translated range. The default starting position is 1. length is 
the range of characters to be translated. If omitted, length remainder of the string from the starting 
position to the end is used. 


Here are some examples: 


TRANSLATE ("abcdef") -> "ABCDEF" 
TRANSLATE("abcdef", , , , 2, 3) -> "aBCDef" 
TRANSLATE("abcdef", "12", "ec") -> "ab2d1f" 
TRANSLATE("abcdef", "12", "abcd", ".") -> "12..ef" 
TRANSLATE("APQRV", , "PR") -> "A Q V" 
TRANSLATE("APQRV", XRANGE("OO"X, "Q")) => "АРЦ " 
TRANSLATE("4123", "abcd", "1234") -> "дарс" 

TRANSLATE("4123", "abcd", "1234", , 2, 2) -> "4ар1" 
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Note: The last example shows how to use the TRANSLATE function to reorder the characters ina 
string. The last character of any four-character string specified as the second argument is moved to 
the beginning of the string. 


7.4.68. TRUNC (Truncate) 


>>-TRUNC (number--4----4--)------------------------------------- >< 


Returns the integer part of number and n decimal places. The default и is 0 and returns an integer with no 
decimal point. If you specify n, it must be a positive whole number or zero. The number is rounded 
according to standard Rexx rules, as though the operation number+0 had been carried out. Then it is 
truncated to n decimal places or trailing zeros are added to reach the specified length. The result is never 
in exponential form. If there are no nonzero digits in the result, any minus sign is removed. 


Here are some examples: 


TRUNC (12.3) -> 12 

TRUNC (127 .09782, 3) -> 127.097 
TRUNC(127.1,3) -> 127.100 
TRUNC (127 , 2) -> 127.00 


Note: The number is rounded according to the current setting of NUMERIC DIGITS, if necessary, 
before the function processes it. 


7.4.69. UPPER 


»»-UPPER(string-4---------------------------- %--)-------------- >< 
%--,--%----- %--%----------- +-+ 


И 


*--n--* +--,length--+ 


Returns a new string with the characters of string beginning with character n for length characters 
converted to uppercase. If n is specified, it must be a positive whole number. If n is not specified, the case 
conversion will start with the first character. If length is specified, it must be a non-negative whole 
number. If length the default is to convert the remainder of the string. 


Examples: 

upper ("Albert Einstein") -> "ALBERT EINSTEIN" 
upper ("abcdef", 4) -» "abcDEF" 
upper("abcdef", 3, 2) -» "abCDef" 
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7.4.70. USERID 


>>-USERID () ---------------------------------------------------- >< 


The return value is the active user identification. 


7.4.71. VALUE 


>>-VALUE (name--4-------------------------------- %--)----------- >< 
%-,--%---------- %--%----------- +-+ 


+-newvalue-+ +-,selector-+ 


Returns the value of the symbol that name (often constructed dynamically) represents and optionally 
assigns a new value to it. By default, VALUE refers to the current Rexx-variables environment, but other, 
external collections of variables can be selected. If you use the function to refer to Rexx variables, name 
must be a valid Rexx symbol. (You can confirm this by using the SYMBOL function.) Lowercase 
characters in name are translated to uppercase for the local environment. For the global environment 
lowercase characters are not translated because the global environment supports mixed-case identifiers. 
Substitution in a compound name (see Compound Symbols) occurs if possible. 


If you specify newvalue, the named variable is assigned this new value. This does not affect the result 
returned; that is, the function returns the value of name as it was before the new assignment. 


Here are some examples: 


/* After: Drop АЗ; A33-7; K=3; fred="K"; list.5="Hi" */ 





VALUE ("a"k) -» "A3" /* looks up A3 */ 
VALUE("a"k||k) -> "7" 
VALUE ("fred") -» "K" /* looks up FRED */ 
VALUE (fred) -» "3" /ж looks up K ж/ 
VALUE(fred,5) -> "3" /ж looks up К and ж/ 
/* then sets K=5 */ 
VALUE (fred) -> "Б" /* looks up К ж/ 
VALUE("LIST."k) -> "Ні" /* looks up LIST.5 */ 


To use VALUE to manipulate environment variables, selector must be the string "ENVIRONMENT" or 
an expression that evaluates to "ENVIRONMENT". In this case, the variable name need not be a valid 
Rexx symbol. Environment variables set by VALUE are not kept after program termination. 


Restriction: The values assigned to the variables must not contain any character that is a hexadecimal 
zero ("00"X). For example: 


Call VALUE "MYVAR", "FIRST" || "OO"X || "SECOND", "ENVIRONMENT" 


sets MYVAR to "FIRST", truncating "00"x and "SECOND". 


Here are some more examples: 


/* Given that an external variable FRED has a value of 4 ж/ 

share = "ENVIRONMENT" 

say VALUE("fred",7,share) /* says "4" and assigns ж/ 
/* FRED а new value of 7 ж/ 
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say VALUE("fred", ,share) /* says "7" ж/ 


/* Accessing and changing Windows environment entries given that ж/ 


/* PATH=C:\EDIT\DOCS; */ 
env = "ENVIRONMENT" 
new = "C:\EDIT\DOCS;" 
say value("PATH",new,env) /ж says "C:\WINDOWS" (perhaps) ж/ 
/* and sets PATH = "C:\EDIT\DOCS;" ж/ 
say value("PATH", ,епу) /* says "C:\EDIT\DOCS;" ж/ 


To delete ап environment variable use the Nil object as the newvalue. To delete the environment variable 
"MYVAR" specify: value("MY VAR", .NIL, "ENVIRONMENT"). If you specify an empty string as the 
newvalue like in value("MY VAR", ", "ENVIRONMENT") the value of the external environment variable is 
set to an empty string which on Windows and *nix is not the same as deleting the environment variable. 


A selector called "WSHENGINE" is also available to the VALUE function when a Rexx script is run in a 
Windows Script Host scripting context (running via cscript, wscript or as embedded code in HTML for 
the Microsoft Internet Explorer). The only currently supported value is "NAMEDITEMS". Calling 
VALUE with these parameters returns an array with the names of the named items that were added at 
script start. 


Example: 
myArray - VALUE("NAMEDITEMS", ,"WSHENGINE") 


The value NAMEDITEMS is read-only, writing to it is prohibited. 


Object Rexx scripts running via the scripting engine (in WSH context) can now call the default method 
of an object as a function call with the object name. 


Example: 

The SESSION object of ASP (Active Server Pages) has the default method VALUE. The usual (and 
recommended) way of using the SESSION object would be to use 
SESSION^VALUE("key","value"). 


Because VALUE is the default method, a function call 


SESSION("key"," value") 
SESSION^VALUE("key"," value"). 


causes an invocation of VALUE with the given arguments. For objects that have the name of a Rexx 
function, an explicit call to the default method must be made, because Rexx functions have priority over 
this implicit method invocation mechanism. 


Note: In contrast to OS/2, the Windows and *nix environments are unchanged after program 


termination. 


You can use the VALUE function to return a value to the global environment directory. To do so, omit 
newvalue and specify selector as the null string. The language processor sends the message name 
(without arguments) to the current environment object. The environment returns the object identified by 
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name. If there is no such object, it returns, by default, the string name with an added initial period (an 
environment symbol--see Environment Symbols). 


Here are some examples: 


/* Assume the environment name MYNAME identifies the string "Simon" */ 
name = value("MYNAME", ,"") /* Sends MYNAME message to the environment */ 
name = .myname /* Same as previous instruction ж/ 
say "Hello," name /* Produces: "Hello, Simon" ж/ 
/* Assume the environment name NONAME does not exist. ж/ 
name = value("NONAME", ,"") /* Sends NONAME message to the environment ж/ 
say "Hello," name /* Produces: "Hello, .NONAME" ж/ 


You can use the VALUE function to change a value in the Rexx environment directory. Include а 
newvalue and specify selector as the null string. The language processor sends the message name (with = 
appended) and the single argument newvalue to the current environment object. After receiving this 
message, the environment identifies the object newvalue by the name name. 


Here is an example: 


name = value("MYNAME","David","") /* Sends "MYNAME=("David") message ж/ 


/* to the environment. ж/ 
/ж You could also use: ж/ 
/ж call value "MYNAME","David","" ж/ 
say "Hello," .myname /* Produces: "Hello, David" ж/ 
Notes: 


1. If the VALUE function refers to an uninitialized Rexx variable, the default value of the variable is 
always returned. The NOVALUE condition is not raised because a reference to an external 
collection of variables never raises NOVALUE. 


2. The VALUE function is used when a variable contains the name of another variable, or when a name 
is constructed dynamically. If you specify name as a single literal string and omit newvalue and 
selector, the symbol is a constant and the string between the quotation marks can usually replace the 
whole function call. For example, fred=VALUE("k") ; is identical with the assignment fred=k;, 
unless the NOVALUE condition is trapped. See Conditions and Condition Traps. 


7.4.72. VAR 


»»-VAR(name)--------------------------------------------------- >< 


Returns 1 if name is the name of a variable, that is, a symbol that has been assigned a value), or 0. 


Here are some examples: 


/* Following: DROP А.З; J-3 ж/ 


VAR(C"J") -> 1 

VAR (J) -» 0 /* has tested "3" ж/ 
VAR("a.j") -> 0 /* has tested "A.3" */ 
VAR(2) -> 0 /* a constant symbol ж/ 
VARC"*") -» 0 /* an invalid symbol */ 
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7.4.73. VERIFY 


»»-VERIFY(string,reference--4---------------------------------------------- %--)--->< 
%-,--%-------- %--%--------------------------- +-+ 


> 


t+-option-+ +-,--+------- %--%--------- +-+ 
*t-start-* +-,length-+ 


Returns a number that, by default, indicates whether string is composed only of characters from 
reference. It returns 0 if all characters in string are in reference, or returns the position of the first 
character in string that is not in reference. 


The option can be either Nomatch (the default) or Match. (Only the capitalized and highlighted letter is 
needed. All characters following it are ignored, and it can be in uppercase or lowercase characters.) If 
you specify Match, the function returns the position of the first character in the string that is in reference, 
or returns 0 if none of the characters are found. 


The default for start is 1; thus, the search starts at the first character of string. You can override this by 
specifying a different start point, which must be a positive whole number. 


The default for length is the length of the string from start to the end of the string. Thus, the search 
proceeds to the end of the receiving string. You can override this by specifying a different length, which 
must be a non-negative whole number. 


If string is null, the function returns 0, regardless of the value of the third argument. Similarly, if start is 
greater than LENGTH (string), the function returns 0. If reference is null, the function returns 0 if you 
specify Match; otherwise, the function returns the start value. 


Here are some examples: 


VERIFY("123","1234567890") -> 0 
УЕВТЕУ ("123","1234567890") -> 2 
VERIFY("ABA4T","1234567890") -> 1 
VERIFY("ABA4T","1234567890" , "M") -> 3 
VERIFY ("AB4T" , "1234567890", "N") -> 1 
VERIFY("1P3Q4","1234567890", ,3) -> 4 
VERIFY ("123","",N,2) -> 2 
VERIFY ("ABCDE","", ,3) -> 3 
VERIFY ("AB3CD5" ,"1234567890" ,"M",4) -> 6 
VERIFY ("ABCDEF" , "ABC", "N",2,3) -> 4 
VERIFY ("ABCDEF" ,"ADEF" ,"M",2,3) -> 4 
7.4.74. WORD 
»»-WORD(string,n)---------------------------------------------- >< 


Returns the nth whitespace-delimited word in string or returns the null string if less than n words are in 
string. n must be a positive whole number. This function is equal to SUBWORD(string, n,1). 


Here are some examples: 


WORD("Now is the time",3) -> "the" 
WORD("Now is the time",5) -» пи 
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7.4.75. WORDINDEX 


»»-WORDINDEX(string,n)----------------------------------------- >< 


Returns the position of the first character in the nth whitespace-delimited word in string or returns 0 if 
less than n words are in string. n must be a positive whole number. 


Here are some examples: 


WORDINDEX("Now is the time",3) -> 8 
WORDINDEX("Now is the time",6) -> 0 


7.4.76. WORDLENGTH 


>>-WORDLENGTH (string ,n) ---------------------------------------- >< 


Returns the length of the nth whitespace-delimited word in the string or returns 0 if less than n words are 
in the string. n must be a positive whole number. 


Here are some examples: 


WORDLENGTH("Now is the time",2) -> 2 
WORDLENGTH("Now comes the time",2) -> 5 
WORDLENGTH("Now is the time",6) -> 0 


7.4.77. WORDPOS (Word Position) 


>>-WORDPOS (phrase, string--+-------- %--)------------------------ >< 
+-,start-+ 


Returns the word number of the first word of phrase found in string or returns 0 if phrase contains no 
words or if phrase is not found. Several whitespace characters between words in either phrase or string 
are treated as a single blank for the comparison, but otherwise the words must match exactly. 


By default, the search starts at the first word in string. You can override this by specifying start (which 
must be positive), the word at which to start the search. 


Here are some examples: 


WORDPOS ("+һе", "now is the time") -> 3 
WORDPOS ("Тһе", "now is the time") -> 0 
WORDPOS("is the","now is the time") -> 2 
WORDPOS ("is the","now is the time") -> 2 
WORDPOS("is time ","now is the time") -> 0 
WORDPOS("be","To be or not to be") -> 2 
WORDPOS("be","To be or not to be",3) -> 6 
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7.4.78. WORDS 
»»-WORDS(string)----------------------------------------------- >< 


Returns the number of whitespace-delimited words in string. 


Here are some examples: 


WORDS("Now is the time") -> 4 
WORDS (" ") -> 0 


7.4.79. Х2В (Hexadecimal to Binary) 
»»-X2B(hexstring)---------------------------------------------- >< 


Returns a string, in character format, that represents hexstring converted to binary. The hexstring is a 
string of hexadecimal characters. It can be of any length. Each hexadecimal character is converted to a 
string of 4 binary digits. You can optionally include whitespace characters in hexstring (at byte 
boundaries only, not leading or trailing) to improve readability; they are ignored. 


The returned string has a length that is a multiple of 4, and does not include any whitespace. 
If hexstring is null, the function returns a null string. 


Here are some examples: 


X2B("C3") -» "11000011" 
X2B("7") -> "0111" 
X2B("1 C1") -> "000111000001" 


You can combine X2B with the functions D2X and C2X to convert numbers or character strings into 
binary form. 


Here are some examples: 


X2B(C2X("C3"x)) -> "11000011" 
X2B(D2X("129")) -» "10000001" 
X2B(D2X("12")) -> "1100" 


7.4.80. X2C (Hexadecimal to Character) 
»»-X2C(hexstring)---------------------------------------------- >< 


Returns a string, in character format, that represents hexstring converted to character. The returned string 
has half as many bytes as the original hexstring. hexstring can be of any length. If necessary, it is padded 
with a leading zero to make an even number of hexadecimal digits. 


You can optionally include whitespace characters in hexstring (at byte boundaries only, not leading or 
trailing) to improve readability; they are ignored. 


If hexstring is null, the function returns a null string. 
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Here are some examples: 


X2C("4865 6c6c 6f") -> 
X2C("3732 73") -> 


"Hello" /* 
"728" /ж 


АЅСІІ ж/ 
АЅСІІ ж/ 


7.4.81. X2D (Hexadecimal to Decimal) 


»»-X2D(hexstring--4----4--)------------------------------------ >< 
t= n= 


Returns the decimal representation of hexstring. The hexstring is a string of hexadecimal characters. If 
the result cannot be expressed as a whole number, an error occurs. That is, the result must not have more 
digits than the current setting of NUMERIC DIGITS. 


You can optionally include whitespace characters in hexstring (at byte boundaries only, not leading or 
trailing) to aid readability; they are ignored. 


If hexstring is null, the function returns 0. 
If you do not specify n, the hexstring is processed as an unsigned binary number. 


Here are some examples: 


X2D("OE") -> 14 

X2D("81") -> 129 

X2D("F81") -> 3969 

X2D("FF81") -> 65409 

X2D("46 30"X) -> 240 Иж ASCII */ 
X2D("66 30"X) -> 240 /ж ASCII */ 


If you specify n, the string is taken as a signed number expressed in п hexadecimal digits. If the leftmost 
bit is off, then the number is positive; otherwise, it is a negative number. In both cases it is converted to a 
whole number, which can be negative. If n is 0, the function returns 0. 


If necessary, hexstring is padded on the left with 0 characters (not "sign-extended"), or truncated on the 
left to n characters. 


Here are some examples: 


X2D("81",2) -> -127 
X2D("81",4) -> 129 
X2D("F081",4) -> -3967 
X2D("F081",3) -> 129 
X2D("F081",2) ->  -127 
X2D("F081",1) => 1 
X2D("0031",0 => 0 


7.4.82. XRANGE (Hexadecimal Range) 


»»-XRANGE(--4------- %--%------ %--)----------------------------- >< 
+-start-+ +-,end-+ 
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Returns a string of all valid 1-byte encodings (in ascending order) between and including the values start 
and end. The default value for start is "00"x, and the default value for end is "FF"x. If start is greater 
than end, the values wrap from "FF"x to "00"x. If specified, start and end must be single characters. 


Here are some examples: 


XRANGE("a" ,"£") -> 
XRANGE("03"x,"07"x) -> 
XRANGE( , "04"x) -> 
XRANGE("FE"x,"02"x) -> 
XRANGE("i","j") -> 
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"abcdef" 

"0304050607"x 

"0001020304" 

"FEFF000102"x 

"ij" /* ASCII */ 
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RexxUtil is a Dynamic Link Library (DLL) package for Windows and *nix platforms; the package 
contains external Rexx functions. These functions: 


+ Manipulate operating system files and directories 
* Manipulate Windows classes and objects 
* Perform text screen input and output 


All of the RexxUtil functions are registered by the ooRexx interpreter on startup so there is no need to 
register the functions either individually or via the SysLoadFuncs function. 


8.1. A Note on Error Codes 


On Windows, some of the REXXUTIL functions return operating system error codes on failure. The 
SysGetErrorText() function can be used retrieve a description of system error code. In addition, the 
meaning of these error return codes can be looked up in the Windows Operating System documentation 
provided by Microsoft. 


The documentation is called the MSDN Library. The library is provided online for anyone to access. Pus, 
since May 2006, Microsoft has also provided the ISO images for the library free of charge. Anyone can 
download the ISOs, burn them to a CD, and install the library locally on their system. 


The information below is provided to help the Rexx programmer locate the MSDN Library, if they would 
like to. All things on the Internet change. The URLs listed here are accurate at the time of this writing. 


The online MSDN Library is currently located at: 
http://msdn2.microsoft.com/en-us/library/default.aspx. 
A direct link to the section on the System Error codes is: 
http://msdn.microsoft.com/en-us/library/ms681381.aspx 


A Google search of MSDN Library will turn up the section on the error codes. A Google search of MSDN 
"System Error Codes" will turn up the section on the error codes. 


Directions to the downloadable ISO images of the MSDN Library have been posted on this blog entry: 
http://blogs.msdn.com/robcaron/archive/2006/07/26/6 7788977 .aspx 


A Google search using: "Rob Caron" General Downloads MSDN Library should also turn up the blog 
entry. 


8.2. List of Rexx Utility Functions 


The following table lists all of the REXXUTIL functions and the platforms on which they are available. 


Table 8-1. Rexx Utility Library Functions 
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Function Name Exists on Platform Remarks 
Windows Unix 

RxMessageBox YES NO 
RxWinExec YES NO 
SysAddRexxMacro YES YES 
SysBootDrive YES NO 
SysClearRexxMacroSpace YES YES 
SysCloseEventSem YES YES 
SysCloseMutexSem YES YES 
SysCls YES YES 
SysCreateEventSem YES YES 
SysCreateMutexSem YES YES 
SysCreatePipe NO Yes 
SysCurPos YES NO 
SysCurState YES NO 
SysDriveInfo YES NO 
SysDriveMap YES NO 
SysDropFuncs YES YES 
SysDropRexxMacro YES YES 
SysDump Variables YES YES 
SysFileCopy YES NO 
SysFileDelete YES YES 
SysFileExists YES YES 
SysFileMove YES NO 
SysFileSearch YES YES 
SysFileSystemType YES NO 
SysFileTree YES YES Works differently 
SysFork NO YES 
бу гот Unicode ҮЕ5 МО 
SysGetErrortext YES YES 
SysGetFileDateTime YES YES 
SysGetKey YES YES 
SysGetMessage NO YES 
SysGetMessageX NO YES 
SysIni YES NO 
SysIsFile YES YES 
SysIsFileCompressed YES NO 
SysIsFileDirectory YES YES 
SysIsFileEncrypted YES NO 
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Function Name Exists on Platform Remarks 
Windows Unix 
SysIsFileLink YES YES 
SysIsFileNotContentIndexed YES NO 
SysIsFileOffline YES NO 
SysIsFileSparse YES NO 
SysIsFileTemporary YES NO 
SysLinVer NO NO* Linux only* 
SysLoadFuncs YES YES 
SysLoadRexxMacroSpace YES YES 
SysMkDir YES YES 
SysOpenEventSem YES YES 
SysOpenMutexSem YES YES 
SysPostEventSem YES YES 
SysPulseEventSem YES NO 
SysQueryProcess YES YES Works differently 
SysQueryRexxMacro YES YES 
SysReleaseMutexSem YES YES 
SysReorderRexxMacro YES YES 
SysRequestMutexSem YES YES 
SysResetEventSem YES YES 
SysRmDir YES YES 
SysSaveRexxMacroSpace YES YES 
SysSearchPath YES YES 
SysSetFileDateTime YES YES 
SysSetPriority YES NO 
SysShutdownSystem YES NO 
SysSleep YES YES 
SysStemCopy YES YES 
SysStemDelete YES YES 
SysStemInsert YES YES 
SysStemSort YES YES 
SysSwitchSession YES NO 
SysSystemDirectory YES NO 
SysTempFileName YES YES 
SysTextScreenRead YES NO 
SysTextScreenSize YES NO 
SysToUnicode YES NO 
SysUtilVersion YES YES 
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Function Name Exists on Platform Remarks 
Windows Unix 

Sys Version YES YES 

Sys VolumeLabel YES NO 
SysWait NO YES 
SysWaitEventSem YES YES 
SysWaitNamedPipe YES NO 
SysWinDecryptFile YES NO 
SysWinEncryptFile YES NO 
SysWinVer YES NO 
SysWinGetPrinters YES NO 
SysWinGetDefaultPrinter YES NO 
SysWinSetDefaultPrinter YES NO 




















8.3. RxMessageBox (Windows only) 


»»-RxMessageBox(text-------------------------------------------- > 
>--%-------------------------------------------- %--)----------- >< 
%-,--%------- %--%-------------------------- +-+ 
+-title-+ +-,--+-------- %--%------- +-+ 


И 


+-button-+ +-,icon-+ 


Displays a Windows message box. 


RxMessageBox returns the selected message box push button. Possible values are: 


1 

The OK push button was pressed 
2 

The CANCEL push button was pressed 
3 

The ABORT push button was pressed 
4 

The RETRY push button was pressed 
5 


The IGNORE push button was pressed 
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The YES push button was pressed 


The NO push button was pressed 


If a message box has a "CANCEL" button, the function returns the 2 value if either the ESC key is 
pressed or the "CANCEL" button is selected. If the message box has no "CANCEL" button, pressing 
ESC has no effect. 


text 


The message box text. 


title 


The message box title. The default title is "Error!". 


button 


The message box push button style. The allowed styles are: 


"NONE" 
No icon is displayed. 
"OK" 


A single OK push button. 


"OKCANCEL" 
An OK push button and a CANCEL push button. 


"RETRYCANCEL" 
A RETRY push button and a CANCEL push button. 


"ABORTRETRYIGNORE" 
An ABORT push button, a RETRY push button and an IGNORE push button. 


"YESNO" 
A YES push button and a NO push button. 


"YESNOCANCEL" 
A YES push button, a NO push button and a CANCEL push button. 
The default push button style is OK. 
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icon 


The message box icon style. The allowed styles are: 


"HAND" 


A hand icon is displayed. 


"QUESTION" 


A question mark icon is displayed. 


"EXCLAMATION" 


An exclamation point icon is displayed. 


"ASTERISK" 


An asterisk icon is displayed. 


"INFORMATION" 


An information icon is displayed. 
"STOP" 

A stop icon is displayed. 
"QUER " 

A query icon is displayed. 
"WARNING" 

A warning icon is displayed. 


"ERROR" 


An error icon is displayed. 


Example: 

/* Give option to quit */ 

if RxMessageBox ("Shall we continue", , "YesNo", "Question") = 7 
Then Exit /* quit option given, exit */ 


8.4. RxWinExec (Windows only) 


»»-RxWinExec(-cmdline--4------------ %--)----------------------- >< 
+-,--cmdshow-+ 


Starts (executes) the application as specified in cmdline. 


Parameters: 
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cmdline 


A string containing a file name and optional parameters for the application to be executed. If the 
name of the executable file in cmdline does not contain a directory path, RxWinExec searches for 
the executable file in this sequence: 


1 
The directory from which Object Rexx was loaded. 
2 
The current directory. 
3 
The Windows system directory. 
4 
The Windows directory. 
5 
The directories listed in the PATH environment variable. 
cmdshow 


Specifies how a Windows-based application window is to be shown. For a non-Windows-based 
application, the PIF file, if any, for the application determines the window state. 


SHOWNORMAL 


Activates and displays a window. 


SHOWNOACTIVATE 


Displays the window while the current active window remains active. 


SHOWMINNOACTIVE 


Displays the window as a minimized window, the current active window remains active. 


SHOWMINIMIZED 


Activates the window and displays it as a minimized window. 


SHOWMAXIMIZED 


Activates the window and displays it as a maximized window. 


HIDE 


Hides the window and activates another window. 


MINIMIZE 


Minimizes the specified window and activates the next top-level window in the Z order. 
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Return codes: 


If the application is started successfully, the process id (PID) is returned. If an error occurs the returned 
value is less than 32. 


Error return codes correspond to a Windows System Error code. If the Windown system error code is 
greater than 32 it is negated. This is to prevent confusion between a legitimate error code and a PID. 


Some common error returns for this function are as follows. 


2 

The specified file was not found. 
3 

The specified path was not found. 
11 

The EXE file is invalid. 
-53 


The network path is invalid. 


8.5. SysAddRexxMacro 


>>-SysAddRexxMacro (паше,#11е-+-------- %-)---------------------- >< 
+-,order-+ 


Adds a routine to the Rexx macrospace. SysAddRexxMacro returns the RexxAddMacro return code. 


Parameters: 


name 


The name of the function added to the macrospace. 


file 


The file containing the Rexx program. 


order 


The macrospace search order. The order can be "B" (Before) or "A" (After). 


8.6. SysBootDrive (Windows only) 


»»-SysBootDrive--(--)------------------------------------------ >< 


Returns the drive used to boot Windows, for example, "С:". 
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8.7. SysClearRexxMacroSpace 


»»-SysClearRexxMacroSpace()------------------------------------ >< 


Clears the Rexx macrospace. SysClearRexxMacroSpace returns the RexxClearMacroSpace return code. 


8.8. SysCloseEventSem 
»»-SysCloseEventSem(handle)------------------------------------ >< 
Closes an event semaphore. 


Parameter: 


handle 
A handle returned from a previous SysCreateEventSem or SysOpenEventSem call. 


Return codes: 


No errors. 


Other 


An error occurred. On Windows, a Windows System Error code is returned. This may be one of the 
following, but could be others. 


Invalid handle. 


102 


Error semaphore busy. 


8.9. SysCloseMutexSem 


»»-SysCloseMutexSem(handle)------------------------------------ >< 


Closes a mutex semaphore. 


Parameter: 


handle 
A handle returned from a previous SysCreateMutexSem call. 


Return codes: 
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0 


No errors. 


Other 


An error occurred. On Windows, a Windows System Error code is returned. This may be one of the 
following, but could be others. 


Invalid handle. 


102 


Error semaphore busy. 


8.10. SysCls 
»»-SysCls()---------------------------------------------------- >< 


Clears the screen. 


Example: 


/* Code */ 
call SysCls 


8.11. SysCreateEventSem 


»»-SysCreateEventSem(-4------ %--%-------------- %-)------------- >< 
+-name-+ +-manual_reset-+ 


Creates or opens an event semaphore. It returns an event semaphore handle that can be used with 
SysCloseEventSem, SysOpenEventSem, SysResetEventSem, SysPostEventSem, and SysWaitEventSem. 
SysCreateEventSem returns a null string ("") if the semaphore cannot be created or opened. 


Parameters: 


name 


The optional event semaphore name. If you omit name, SysCreateEventSem creates an unnamed, 
shared event semaphore. If you specify name, SysCreateEventSem opens the semaphore if the 
semaphore has already been created. A semaphore name can be MAX PATH long, and can contain 
any character except the backslash (\) path-separator character. Semaphore names are case-sensitive. 


manual_reset 


A flag to indicate that the event semaphore must be reset manually by SysResetEventSem. If this 
parameter is omitted, the event semaphore is reset automatically by SysWaitEventSem. 
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8.12. SysCreateMutexSem 


»»-SysCreateMutexSem(-4------ %-)------------------------------- >< 
+-паше-+ 


Creates ог opens а mutex semaphore. Returns a mutex semaphore handle that can be used with 
SysCloseMutexSem, SysRequestMutexSem, and SysReleaseMutexSem. SysCreateMutexSem returns a 
null string ("") if the semaphore cannot be created or opened. 


Parameter: 


name 


The optional mutex semaphore name. If you omit name, SysCreateMutexSem creates an unnamed, 
shared mutex semaphore. If you specify name, SysCreateMutexSem opens the semaphore if the 
mutex has already been created. The semaphore names cannot be longer than 63 characters. 
Semaphore names are case-sensitive. 


8.13. SysCreatePipe (Unix only) 
»»-SysCreatePipe()--------------------------------------------- >< 


Creates an unnamed pipe. 
Returns: 


Returns a string like "handle handle" where the first handle is for read and the second handle for write. 


8.14. SysCurPos (Windows only) 


»»-SysCurPos(-4------------ аа-а === >< 
+-row,column-+ 


Returns the cursor position in the form row col and optionally moves the cursor to a new location. 
Parameters: 
row 

The row to move to. 


col 


The column to move to. 


Note: Position (0,0) is the upper left corner. 


You can call SysCurPos without a column and row position to obtain the cursor position without moving 
the cursor. 
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Example: 
/* Code */ 
call SysCls 


parse value SysCurPos() with row col 
say "Cursor position is "row", "col 


/* Output */ 
Cursor position is 0, 0 


8.15. SysCurState (Windows only) 


»»-SysCurState(state)------------------------------------------ >< 
Hides or displays the cursor. 


Parameter: 


State 


The new cursor state. Allowed states are: 
"ON" 
Display the cursor 


"OFF" 


Hide the cursor 


8.16. SysDrivelnfo (Windows only) 
»»-SysDriveInfo(drive)----------------------------------------- >< 
Returns drive information in the form: drive: free total label. 
drive: 
is the drive letter identifier. 


free 


is the drive unused space. 


total 


is the total size of the drive. 
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label 
is the drive label. 
If the drive is not accessible, then SysDriveInfo returns "". 


Parameter: 


drive 
The drive of interest, "C:". 


Example: 


/* Code */ 

say "Disk-"SysDriveInfo("C:") 

/* Output */ 

Disk-C: 33392640 83687424 TRIGGER C 


8.17. SysDriveMap (Windows only) 


»»-SysDriveMap(-4------- +-+------ $a) нгі ілі сігіс еілшіліші нісін >< 
+-drive-+ +-,opt-+ 


Returns a string listing accessible drives (separated by blanks) in the form: C: D: .... 


Parameters: 


drive 


The first drive letter of the drive map. The default is "C:". 


opt 
The drivemap option. This can be: 


"USED" 


returns the drives that are accessible or in use, including all local and remote drives. This is the 
default. 


"FREE" 


returns drives that are free or not in use. 


"LOCAL" 


returns only local drives. 


"REMOTE" 


returns only remote drives, such as redirected LAN resources or installable file system (IFS) 
attached drives. 
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"REMOVABLE" 


returns removable drives. 


"CDROM" 
returns CD-ROM drives. 


"RAMDISK" 


returns drives assigned from RAM. 


Example: 

/* Code */ 

say "Used drives include:" 
say SysDriveMap("C:", "USED") 


/* Output */ 
Used drives include: 
C: D: E: F: W: 


8.18. SysDropFuncs 


From ooRexx 4.0.0 and on this function does nothing. 


8.19. SysDropRexxMacro 


>>-SysDropRexxMacro (name)-------------------------------------- >< 


Removes a routine from the Rexx macrospace. SysDropRexxMacro returns the RexxDropMacro return 
code. 


Parameter: 


name 


The name of the function removed from the macrospace. 


8.20. SysDumpVariables 


>>-SysDumpVariables-+------------ n cL T SSS esas >< 
+-(--паше--) -+ 


Dumps all variables in the current scope either to the specified file filename (new data is appended) or to 
STDOUT if you omit filename. The format of the data is, with one variable per line: 


Name=MYVAR, Value="This is the content of MYVAR" 
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Parameter: 


filename 


The name of the file to which variables are appended. The dump is written to STDOUT if you omit 
this parameter. 


Return codes: 


0 

Dump completed successfully. 
-1 

Dump failed. 
Example: 


Call SysDumpVariables "MyVars.Lst" /* append vars to file */ 
Call SysDumpVariables /* list vars on STDOUT */ 


8.21. SysFileCopy (Windows only) 
>>-SysFileCopy(source, target)--------------------------------- >< 


Copies a file from one location to another. Wildcard file specifications are not allowed. 


Parameter: 


source 


The path/name of the file to be copied. 


target 
The path/name of the target location where the file is to be copied. 


Return codes: 


File copied successfully. 


Other 
A Windows System Error code. 


Example: 


/* Code */ 
call SysFileCopy "c:\temp\myfile.txt", "d:\myfolder" 
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8.22. SysFileDelete 


»»-SysFileDelete(file)----------------------------------------- >< 


Deletes a file. SysFileDelete does not support wildcard file specifications. 


Parameter: 


file 
The name of the file to be deleted. 


Return codes: 


0 
File deleted successfully. 
Other 
An error occurred. On Windows, a Windows System Error code is returned. This may be one of the 
following, but could be others. 
2 
File not found. 
3 
Path not found. 
5 
Access denied or busy. 
26 
Not DOS disk. 
32 
Sharing violation. 
36 
Sharing buffer exceeded. 
87 
Does not exist. 
206 
File name exceeds range error. 
Example: 
/* Code */ 


parse arg InputFile OutputFile 
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call SysFileDelete OutputFile /* unconditionally erase output file */ 


8.23. SysFileExists 


»»-SysFileExists(filename)----------------------------------------- >< 


Checks for the existence of a file. This function does not support wildcard specifications. Returns true if 
any file system entity with the given name exists. In particular, this will return true for both regular files 
and directories. 


Parameters: 


filename 
The name of the file to check for the existence of. 


Returns: 


The file does not exist. 


The file exists. 


Example: 


if SysFileExists(InputFile) then say "File Exists!" 
else say "File does not exist." 


8.24. SysFileMove (Windows only) 


>>-SysFileMove(source, target)--------------------------------- >< 


Moves a file from one location to another. Wildcard file specifications are not allowed. 


Parameter: 


source 


The path/name of the file to be moved. 


target 


The path of the target location where the file is to be moved. The target must contain a path 
component. 


Return codes: 
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0 


File copied successfully. 


Other 
On failure, a Windows System Error code is returned. 


Example: 


/* Code */ 
call SysFileMove "c:\temp\myfile.txt", "d:\myfolder" 


8.25. SysFileSearch 


»»-SysFileSearch(target,file,stem--4---------- +--) ------------- >< 
+-,options-+ 


Finds all file lines containing the target string and returns the file lines in a Rexx stem variable collection. 


Parameters: 


target 


The target search string. 


file 
The searched file. 


stem 


The result stem variable name. SysFileSearch sets Rexx variable stem.0 to the number of lines 
returned and stores the individual lines in variables stem. to stem.n. 


options 


Any combination of the following one-character options: 
"С" 
Conducts a case-sensitive search. 


"N" 
Returns the file line numbers. 
The default is a case-insensitive search without line numbers. 


Return codes: 


Successful. 
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2 

Not enough memory. 
3 

Error opening file. 
Example: 


/* Find DEVICE statements in CONFIG.SYS ж/ 

call SysFileSearch "DEVICE", "C:\CONFIG.SYS", "file." 
do i-1 to Ғ11е.0 

say file.i 

end 


/* Output */ 

DEVICE-C:NSB16NDRVNCTSB16.SYS /UNIT=0 /BLASTER-A:240 І:5 D:1 H:5 
DEVICE-C:NSB16NDRVNCTMMSYS . SYS 

rem жжжж DOS SCSI CDROM device drivers *** 
DEVICE-C:NSCSIMASPI8DOS.SYS /D 
DEVICE=C:\SCSI\ASPICD.SYS /D:ASPICDO 

rem **** IDE CDROM device drivers 

DEVICE=C: \DOS\HIMEM.SYS 

DEVICE=C:\SBCD\DRV\SBIDE.SYS /V /D:MSCDOO1 /P:1f0,14 
DEVICE=C: \DOS\SETVER. EXE 

DEVICE=C: \WINDOWS\SMARTDRV.EXE /DOUBLE BUFFER 
DEVICE=C: \WINDOWS\IFSHLP. SYS 


/* Find DEVICE statements in CONFIG.SYS (along with */ 

/* line numbers) */ 
call SysFileSearch "DEVICE", "C:\CONFIG.SYS", "file.", "N" 
do ізі to file.O 

say file.i 

end 


/* Output */ 

DEVICE-C:NSB16NDRVNCTSB16.SYS /UNIT-O /BLASTER-A:240 I:5 D:1 
:5b 

DEVICE-C:NSB16NDRVNCTMMSYS . SYS 

rem жжжж DOS SCSI CDROM device drivers *** 
DEVICE=C:\SCSI\ASPI8D0S.SYS /D 
DEVICE=C:\SCSI\ASPICD.SYS /D:ASPICDO 

rem **** IDE CDROM device drivers 

DEVICE=C: \DOS\HIMEM.SYS 

10 DEVICE=C:\SBCD\DRV\SBIDE.SYS /V /D:MSCDOO1 /P:1f0,14 
13 DEVICE=C: \DOS\SETVER. EXE 

16 DEVICE=C: \WINDOWS\SMARTDRV.EXE /DOUBLE_BUFFER 

17 DEVICE=C: \WINDOWS\IFSHLP.SYS 


оооло Ge 
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8.26. SysFileSystemType (Windows only) 


>>-SysFileSystemType (drive)------------------------------------ >< 
Returns the name of the file system used for a drive. If the drive is not accessible, it returns a null string 


e. 


Parameter: 


drive 
The drive of interest, for example "C:". 


Example: 
/* Code */ 
say "File System-"SysFileSystemType("C:") 


/* Output */ 
File System-NTFS 


8.27. SysFileTree 


»»-SysFileTree(filespec,stem------------------------------------ ? 
>--%------------------------------------------------------- %----> 
%-,--%--------- %--%----------------------------------- +-+ 
+-оръпопв-# + 4 ---5---< +--+--------------- +-+ 
+-tattrib-+ +-,-+---------+-+ 


+-nattrib-+ 
>--)----------------------------------------------------------- >< 


Finds all files that match а file specification. SysFileTree returns the file descriptions (date, time, size, 
attributes, and file specification) space delimited in a Rexx stem variable collection. The default format 
for date and time is platform specific. 


Parameters: 


filespec 


The search file specification. 


stem 


The name of a stem variable to be used for storing results. SysFileTree sets Rexx variable stem.0 to 
the number of files and directories found and stores individual file descriptions into variables stem. / 
to stem.n. Note: stem can be specified as stem or stem. (with or without the trailing period) 


options 


A string with any combination of the following: 


454 ooRexx Reference Version 4.0.0 


Chapter 8. Rexx Utilities (RexxUtil) 


"EU 
Search only for files. 

"D" 
Search only for directories. 

"В" 
Search for both files and directories. This is the default. 

"Sn 
Search subdirectories recursively. 

mp 
Return the time and date in the form YY/MM/DD/HH/MM. If the "L" option is also specified 
then this option will be ignored. 

ы Wh 
Return the time and date in the form YYY Y-MM-DD HH:MM:SS. 

"I" 
Perform a case-insensitive search for file names/directories. This option is only used on system 
that support case-sensitive file names and is ignored on systems like Windows where the file 
system is case-insensitive by default. 

"О" 
Return only the fully-qualified file name. 

tattrib 
The target attribute mask for file specification matches. Only files that match the target mask 
are returned. The default mask is "*****", This returns all files regardless of the settings (clear 
or set) of the Archive, Directory, Hidden, Read-Only, and System attributes. The target mask 
attributes must appear in the order "ADHRS". 

Target Mask Options 

ж 
The file attribute may be any state. 

+ 
The file attribute must be set. 
The file attribute must be cleared. 

Target Mask Examples 
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таяна" 
Find all files with the Read-Only attribute set. 
Wa. sio pot 
Find all files with the Read-Only and Archive attributes set. 
TR ose t 
Find all hidden subdirectories. 


" " 
---+- 


Find all files with only the Read-Only attribute set. 


nattrib 


The new attribute mask for setting the attributes of each matching file. The default mask is "ЖЖ 
This means not to change the Archive, Directory, Hidden, Read-Only, and System attributes. The 
target mask attributes must appear in the order "ADHRS". 


New Attribute Mask Options 


Do not change the file attribute. 


Set the file attribute. 


Clear the file attribute. 


New Attribute Mask Examples 


mkkk pk" 

Set the Read-Only attribute on all files. 
"kkp" 

Set the Read-Only attribute and clear the Archive attribute of each file. 
"+*+" 

Set all file attributes, except the directory attribute. 


" " 


Clear all attributes on all files. 


Note: You cannot set the directory attribute on non-directory files. SysFileTree returns the file 
attribute settings after the new attribute mask has been applied. 
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Return codes: 


0 

Successful. 
2 

Not enough memory. 
Examples: 


/* Find all subdirectories on C: ж/ 


call SysFileTree "c:\*.*", "file", "SD" 
/* Find all Read-Only files */ 
call SysFileTree "c:\*.*", "file", "S", "жжж+ж" 


/* Clear Archive and Read-Only attributes of files that have them set */ 
call SysFileTree "c:\*.*", "file", "S", "+жж+ж", "-жж-ж" 








/жжжж< < Sample Code and Output Ехашр!е.>>жжжжжжжж/ 


/* Code */ 

call SysFileTree "c:Nwin*.", "file", "В" 
do ізі to file.O 

say file.i 

end 


/* Actual Output */ 
5:24:95 4:59p 0 -D--- C:\WINDOWS 


8.28. SysFork (Unix only) 


»»-SysFork()--------------------------------------------------- >< 


Returns 

Returns the process id to the parent process. 
Returns 0 to the spawned process. 
Example: 


This is a complete working example. It can be cut and pasted into a file and executed on a Unix system. 


/* Example Unix SysFork() and SysWait() */ 


pid = SysFork() 
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if pid == 0 then do 
say "I am the child." 
code = executeChild() 
say "Child : done with execution, will exit with" code 
exit code 
end 
else do 
say ’I am the parent, child pid is:’ pid 
code = executeParent () 
say ’Parent: going to wait for child.’ 
code = SysWait() 
say ’Parent: back from waiting. Child exit code: code 
end 


say ’Operating system version:? SysVersion() 
::routine executeChild 
say ’Child : will sleep 1 second.’ 


j = SysSleep(1) 
say ”СҺ114 : done sleeping 1. Will do some calculations.’ 


total = 0 
do 786 

total += 3 
end 


say ’Child : 3 * 786 is:’ total 


say ’Child : will sleep 2 seconds.’ 
j = SysSleep(2) 
say ”СҺ114 : done sleeping 2. Will do some calculations.’ 


total - O 
do 1865 
total += 7 
end 
say "Child : 7 ж 1865 is:’ total 


say ’Child : will sleep 2 seconds.’ 

j = SysSleep(2) 

say ’Child : done sleeping 2.’ 

say ’Child : done executing, will return 0.’ 
return 0 


::routine executeParent 
say ’Parent: 3 * 786 is:’ (3 * 786) 
j = SysSleep(2) 


say ’Parent: 7 ж 1865 is:’ (7 ж 1865) 
return 0 
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8.29. SysFromUnicode (Windows only) 
»»-SysFromUnicode--(--string, codepage, mappingflags,----------- > 
>--, defaultchar, outstem--)----------------------------------- >< 
Maps a UNICODE character string to an ASCII character string. The new character string and additional 


information is returned in the outstem. 


Parameters: 


string 


A string containing the UNICODE characters to be mapped. 


codepage 


Specifies the code page used to perform the conversion. This parameter can be the value of any code 
page that is installed or available in the system. The default is the current original equipment 
manufacturer (OEM) code-page identifier for the system. 


You can also specify one of the following values: 


ACP 
ANSI code page. 


OEMCP 
OEM code page. 


SYMBOL 
Windows 2000: symbol code page. 


THREAD_ACP 
Windows 2000: current thread’s ANSI code page. 


UTF7 
Windows NT 4.0 and Windows 2000: translate using UTF-7. 


UTF8 


Windows NT 4.0 and Windows 2000: translate using UTF-8. When this is set, mappingflags 
must be set. 


mappingflags 
Specifies the handling of unmapped characters. The function performs more quickly when none of 
these flags is set. 


The following flags can be used: 
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COMPOSITECHECK 


Converts composite characters to precomposed characters. 


SEPCHARS 


Generates separate characters during conversion. This is the default conversion behavior. 


DISCARDNS 


Discards nonspacing characters during conversion. 


DEFAULTCHAR 
Replaces non-convertible characters with the default character during conversion. 


When compositecheck is specified, the function converts composite characters to precomposed 
characters. A composite character consists of a base character and a nonspacing character, each 
having different character values. A precomposed character has a single character value for a 
combination of a base and a nonspacing character. In the character е, the "e" is the base character, 
and the "grave" accent mark is the nonspacing character. 


When compositecheck is specified, it can use the last three flags in this list (discardns, sepchars, 
and defaultchar) to customize the conversion to precomposed characters. These flags determine 
the function’s behavior when there is no precomposed mapping for a combination of a base and a 
nonspace character in a Unicode character string. These last three flags can be used only if the 
compositecheck flag is set. The function’s default behavior is to generate separate characters 
(sepchars) for unmapped composite characters. 


defaultchar 


Character to be used if a Unicode character cannot be represented in the specified code page. If this 
parameter is NULL, a system default value is used. The function is faster when defaultchar is not 
used. 


outstem 


The name of the stem variable that will contain the converted result. If the conversion was 
successful the stem will be composed of the following value(s): 


outstem.!USEDDEFAULT char 


This variable will be set to "1" if the defaultchar was used during the conversion and "0" if it 
was not. 


outstem.!TEXT 


This variable will contain the converted string. 


Return codes: 


No errors. 
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Other 
An error occurred. A Windows System Error code is returned. This may be one of the following, but 
could be others. 

87 


Incorrect code page or codepage value. 


1004 
Invalid mapping flags. 


8.30. SysGetErrortext 


>>-SysGetErrortext (errornumber)-------------------------------- >< 


Obtains a string describing the system error identified by the error number. 

Returns a string with the description of the error, or an empty string if no description is available. 
Windows Example: 

err=SysMkDir("c:\temp") 


if err \= 0 then 
say "Error" err":"SysGetErrortext (err) 


Unix Example: 


err=SysMkDir ("/home/NotKnown/temp") 
if err \= 0 then 
say "Error" err":"SysGetErrortext (err) 


8.31. SysGetFileDateTime 


»»-SysGetFileDateTime(filename-4------------ %-)---------------- >< 
+-,--timesel-+ 


Returns the selected data and time attribute of the file filename provided that this is supported by the 
operating and file system. FAT, for example, does not support Create/Access. The selector for the time to 
be returned can be abbreviated to the first character. 


The filename can also be a directory name. 


The file that you want to query must not be opened by another process or must at least allow shared 
writes to query the time stamp. 


Parameters: 


filename 


The name of the file to be queried. 
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timesel 
The file time to be queried, namely CREATE, ACCESS, WRITE. 
Return codes: 


The date and time in the format Y Y YY-MM-DD HH:MM:SS, or -1 to indicate that the file date and time 
query failed 


Example: 


Say "File creation time:" SysGetFileDateTime("MyFile.Log", "C") 
Say "File last access time:" SysGetFileDateTime("MyFile.Log", "A") 
Say "File last update time:" SysGetFileDateTime("MyFile.Log", "W") 


Say "Directory creation time:" SysGetFileDateTime("C:\MyDir", "C") 
/* in Windows NT */ 


8.32. SysGetKey 


>>-SysGetKey (-+----- %-)---------------------------------------- >< 
%-ор%-% 


Reads and returns the next key from the keyboard buffer. If the keyboard buffer is empty, SysGetKey 
waits until a key is pressed. Unlike the CHARIN built-in function, SysGetKey does not wait until the 
Enter key is pressed. 


Parameter: 


opt 


An option controlling screen echoing. Allowed values are: 


"ECHO" 


Echo the pressed key to the screen. This is the default. 


"NOECHO" 
Do not echo the pressed key. 


8.33. SysGetMessage (Unix only) 


>>-SysGetMessage (num--4------------------------------- %--)----- >< 
*t--,--filename--4--------------- * 
| [i ====--==6 + | 
| | v | | 
| +---- ,--str--+--+ 
|, "pneum * | 
| v | | 
q-———— ;4T7—Str--2t-2------————----4- + 
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Retrieves a message from a catalog file and replaces the placeholder %s with the text you specify. 
SysGetMessage can replace up to 9 placeholders. 
This utility is implemented for Unix only. 
To create catalog files, consult your system documentation. 


Parameters: 


The message number. 


filename 
The name of the catalog file containing the message. The default message catalog is rexx.cat. 
SysGetMessage searches along the NLSPATH or uses the absolute path name. 

str 


The test for a placeholder (%) in the message. The message can contain up to 9 placeholders. You 
must specify as many strings as there are placeholders in the message. 


Example: 


/* sample code segment using SysGetMessage */ 
msg = SysGetMessage(485, "rexx.cat", foo) 

say msg 

/*** Output жжж/ 

Class "foo" not found. 


8.34. SysGetMessageX (Unix only) 


»»-SysGetMessageX(set,num--4------------------------------- %--)->< 
t--,--filename--4--------------- * 
| Г eR + 4 
| | v | | 
| +---- ,--str--+--+ 
|; x * | 
| ov | | 
==>, ;T-Str--t------------———-—- * 


Retrieves a message from a specific set of Unix catalog file and replaces the placeholder 4s with the text 
you specify. SysGetMessageX can replace up to 9 placeholders. 


This utility is implemented for Unix only. Do not use it for platform-independent programs. 
To create catalog files, consult your system documentation. 


Parameters: 


set 


The message set. 


ooRexx Reference Version 4.0.0 463 


Chapter 8. Rexx Utilities (RexxUtil) 


num 


The message number. 


filename 
The name of the catalog file containing the message. The default message catalog is rexx.cat. 
SysGetMessageX searches along the NLSPATH or uses the absolute path name. 

str 


The test for a placeholder (%) in the message. The message can contain up to 9 placeholders. You 
must specify as many strings as there are placeholders in the message. 


Example: 

/* sample code segment using SysGetMessage */ 
msg = SysGetMessageX(1, 485, "rexx.cat", foo) 
say msg 

/*** Output жжж/ 

Class "foo" not found. 


8.35. Syslni (Windows only) 


»»-SysIni(-4--------- *-,app,key,val,stem-)--------------------- >< 
+-inifile-+ 


Allows limited access to INI file variables. Variables are stored in the INI file under Application Names 
and their associated key names or keywords. You can use SysIni to share variables between applications 
or as a way of implementing GLOBALYV in the Windows operating system. Be careful when changing 
application profile information. 


Note: Syslni works on all types of data stored in an INI file (text, numeric, or binary). 


When SysIni successfully sets or deletes key values, it returns "". For a successful query, it returns the 
value of the specified application keyword. 


SysIni may return the string ERROR: when an error occurs. Possible error conditions include: 


“ An attempt was made to query or delete an application/key pair that does not exist. 


* Anerror opening the profile file occurred. You may have specified the current user or system INI file 
with a relative file specification. Make sure to use the full file specification (specify drive, path, and 
file name). 


Parameters: 
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inifile 
The name of the INI file with which you would like to work. The default is WIN.INI. 
Note: If this argument does not contain a fully qualified file name, the Windows operating system 


searches for the file in the Windows directory. Therefore to work with a file outside of the 
Windows directory, specify the full path name of the file. 


app 


The application name or some other meaningful value with which you want to store keywords 
(some sort of data). 


key 
The name of a keyword to hold data. 


val 


The value to associate with the keyword of the specified application. This can be "DELETE: " or 
"ALL: ". 


stem 


The name of a Rexx stem variable collection in which to store the resultant information. SysIni sets 
Rexx variable stem.0 to the number of elements returned and stores these elements in stem. to 
stem.n. 


Sysini has six modes. The modes and the syntax variations are as follows: 


»»-SysIni(-4--------- *-,app,key,val)--------------------------- >< 
+-inifile-+ 


Sets a single key value. 


>>-SysIni (-+--------- *-,app,key)------------------------------- >< 
+-inifile-+ 


Queries a single key value. 


»»-SysIni(-4--------- *-,app,key--, "DELETE: "-)------------------ >< 
+-inifile-+ 


Deletes a single key. 


»»-SysIni(-4--------- *-,app-*------------ %-)------------------- >< 
+-inifile-+ +- , "DELETE: "-+ 


Deletes an application and all associated keys. 


»»-SysIni(-4--------- *-,app--,"ALL:"--,"stem"-)---------------- >< 
+-inifile-+ 


Queries names of all keys associated with a certain application. 
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»»-SysIni(-4--------- *-,"ALL:"--,"stem"-)---------------------- >< 
+-inifile-+ 


Queries the names of all applications. 


Examples: 


/* Sample code segments */ 


/*** Save the user entered name under the key "NAME" of жжжжж 


жжжж the application "MYAPP". жжжж/ 
pull name . 

call SysIni , "MYAPP", "NAME", name /* Save the value ж/ 
say SysIni(, "MYAPP", "NAME") /* Query the value ж/ 
call SysIni , "MYAPP" /* Delete all MYAPP info */ 
exit 


/жжжж Type all WIN.INI file information to the screen жжжжж/ 
call SysIni "WIN.INI", "А11:", "Apps." 

if Result \= "ERROR:" then 

do i = 1 to Apps.O 

call SysIni "WIN.INI", Apps.i, "All:", "Keys" 
if Result \= "ERROR:" then 

do ј=1 to Кеув.0 

val - SysIni("WIN.INI", Apps.i, Keys.j) 

say left(Apps.i, 20) left(Keys.j, 20), 
"Len-x"Left(d2x(length(val)),4) left(val, 20) 
end 





end 
exit 


8.36. SyslsFile 


»»-SysIsFile(filename)----------------------------------------- >< 


Checks for the existence of a file. This function does not support wildcard specifications. 
On Linux/Unix block devices are also considered to be regular files by this function. 


Parameters: 


filename 
The name of the file to check for the existence of. 


Returns: 


The file does not exist. 
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The file exists. 


Example: 


if SysIsFile(InputFile) then say "File Exists!" 
else say "File does not exist." 


8.37. SysisFileCompressed (Windows only) 


»»-SysIsFileCompressed(filename)------------------------------- >< 


Checks if a file is compressed. This function does not support wildcard specifications. 


Parameters: 


filename 
The name of the file to check. 


Returns: 


The file is not compressed or does not exist. 


The file is compressed. 


Example: 


if SysIsFileCompressed(InputFile) then say "File is compressed!" 
else say "File is not compressed or does not exist." 


8.38. SyslsFileDirectory 


>>-SysIsFileDirectory (dirname)--------------------------------- >< 


Checks for the existence of a subdirectory. This function does not support wildcard specifications. 


Parameters: 


dirname 
The name of the subdirectory to check for the existence of. 


Returns: 
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0 

The subdirectory does not exist. 
1 

The subdirectory exists. 
Example: 


if SysIsFileDirectory(InputFile) then say "Subdirectory Exists!" 
else say "Subdirectory does not exist." 


8.39. SysisFileEncrypted (Windows only) 


»»-SysIsFileEncrypted(filename)-------------------------------- >< 
Checks if a file is encrypted. This function does not support wildcard specifications. 


Parameters: 


filename 
The name of the file to check. 


Returns: 


The file is not encrypted or does not exist. 


The file is encrypted. 


Example: 


if SysIsFileEncrypted(InputFile) then say "File is encrypted!" 
else say "File is not encrypted or does not exist." 


8.40. SyslsFileLink 


»»-SysIsFileLink(linkname)------------------------------------- >< 


Checks for the existence of a link. This function does not support wildcard specifications. 


Parameters: 
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linkname 
The name of the link to check for the existence of. 


Returns: 


The link does not exist or it is not a link. 


The link exists. 


Example: 


if SysIsFileLink(InputFile) then say "Link Exists!" 
else say "Link does not exist." 


8.41. SysisFileNotContentindexed (Windows only) 
>>-SysIsFileNotContent Indexed (filename) ------------------------ >< 


Checks if a file is flagged to be indexed by the Index Service. This function does not support wildcard 
specifications. 


Parameters: 


filename 
The name of the file to check. 


Returns: 


The file is not flagged to be Indexed or does not exist. 


The file is flagged to be Indexed. 


Example: 


if SysIsFileNotContentIndexed(InputFile) then say "File is flagged to be Indexed!" 
else say "File is not flagged to be Indexed." 


8.42. SyslsFileOffline (Windows only) 


»»-SysIsFileO0ffline(filename)---------------------------------- >< 


Checks if a file is flagged as Offline. This function does not support wildcard specifications. 
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Parameters: 
filename 


The name of the file to check. 


Returns: 


The file is not flagged as Offline or does not exist. 


The file is flagged as Offline. 


Example: 


if SysIsFileOffline(InputFile) then say "File is flagged as Offline!" 
else say "File is not flagged as Offline." 


8.43. SysisFileSparse (Windows only) 


»»-SysIsFileSparse(filename)----------------------------------- >< 


Checks if a file is flagged as Sparse. This function does not support wildcard specifications. 


Parameters: 


filename 
The name of the file, subdirectory or link to check. 


Returns: 


The file is not flagged as Sparse or does not exist. 


The file is flagged as Sparse. 


Example: 


if SysIsFileSparse(InputFile) then say "File is Sparse!" 
else say "File is not Sparse." 


8.44. SyslsFileTemporary (Windows only) 


>>-SysIsFileTemporary (filename)-------------------------------- >< 
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Checks if a file is flagged as Temporary. This function does not support wildcard specifications. 


Parameters: 


filename 
The name of the file, subdirectory or link to check. 


Returns: 


The file is not flagged as Temporary or does not exist. 


The file is flagged as Temporary. 


Example: 


if SysIsFileTemporary(InputFile) then say "File is Temporary!" 
else say "File is not Temporary." 


8.45. SysLinVer (Linux Only) 


»»-SysLinVer()------------------------------------------------- >< 


Returns a string identifying the Linux system version. The first word of the returned string is Linux and 
the second word in the string identifies the kernel version. A possible output for a Linux system might be: 


Say SysLinVer() -» "Linux 2006.2.6.18-1.2798.fc6" 


8.46. SysLoadFuncs 


>> oy SLOAdPUNCs s soe sea SSS SS SSeS SSeS eR Se eorpora >< 


From ooRexx 4.0.0 and on this function does nothing. 


8.47. SysLoadRexxMacroSpace 
>>-SysLoadRexxMacroSpace (file) --------------------------------- >< 


Loads functions from a saved macrospace file. SysLoadRexxMacroSpace returns the 
RexxLoadMacroSpace return code. 


Parameter: 
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file 


The file used to load functions into the Rexx macrospace. SysSaveRexxMacroSpace must have 
created the file. 


8.48. SysMkDir 


»»-SysMkDir(dirspec)------------------------------------------- >< 


Creates a specified directory. 


Parameter: 


dirspec 
The directory to be created. 


Return codes: 


0 
Directory creation was successful. 
Other 
An error occurred. On Windows, a Windows System Error code is returned. This may be one of the 
following, but could be others. 
2 
File not found. 
3 
Path not found. 
5 
Access denied. 
26 
Not a DOS disk. 
87 
Invalid parameter. 
108 
Drive locked. 
183 


Directory already exists. 
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206 
File name exceeds range. 


Example: 


/* Code */ 
call SysMkDir "rexx" 


8.49. SysOpenEventSem 


»»-SysÜpenEventSem(name)--------------------------------------- >< 


Opens an event semaphore. SysOpenEventSem returns a handle to the semaphore, or zero if an error 
occurred. 


Parameter: 


name 


The name of the event semaphore created by SysCreateEventSem. 


8.50. SysOpenMutexSem 


»»-SysÜpenMutexSem(name)--------------------------------------- >< 


Opens a mutex semaphore. SysOpenMutexSem returns a handle to the semaphore, or zero if an error 
occurred. 


Parameter: 


name 


The name of the mutex semaphore created by SysCreateMutexSem. 


8.51. SysPostEventSem 
»»-SysPostEventSem(handle)------------------------------------- >< 
Posts an event semaphore. 


Parameter: 


handle 
A handle returned from a previous SysCreateEventSem call. 


Return codes: 
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0 
No errors. 

Other 
An error occurred. On Windows, a Windows System Error code is returned. This may be one of the 
following, but could be others. 

6 


Invalid handle. 


8.52. SysPulseEventSem (Windows only) 


»»-SysPulseEventSem(handle)------------------------------------ >< 


Posts and immediately resets an event semaphore. It sets the state of the event to signaled (available), 
releases any waiting threads, and resets it to nonsignaled (unavailable) automatically. If the event is 
manual, all waiting threads are released, the event is set to nonsignaled, and PulseEvent returns. If the 
event is automatic, a single thread is released, the event is set to nonsignaled, and PulseEvent returns. If 
no threads are waiting, or no threads can be released immediately, PulseEvent sets the state of the event 
to nonsignaled and returns. 


SysPulseEventSem returns 0 on success and a Windows System Error code is returned on error. . 


Parameter: 


handle 


The handle of an event semaphore previously created by SysCreateEventSem. 


8.53. SysQueryProcess 


Windows 
+-РІр---+ 
>>-SysQueryProcess(" -+-ТІр---+- ")---------------------------- >< 
+-PPRIO-+ 
+-TPRIO-+ 
+-PTIME-+ 
+-TTIME-+ 
Unix 
+-PID------ + 
>>-SysQueryProcess(" -4---------- Ееее ШІ? fraser дін oes pee a тя >< 
+-PPID----- + 


+-PPRIO----+ 
+-РТІМЕ----+ 
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Retrieves information about the current process or Windows thread. 


+-PSWAPS---+ 
+-PRCVDSIG-+ 


Parameter: 


info 


The kind of information requested: 


PID 


Returns the process ID of the current process. 


PPID 


Returns the parent process ID of the current process. 


TID 


Returns the thread ID of the current thread. 


PPRIO 


Returns the priority class of the current process. 


TPRIO 


Returns the relative priority of the current thread. 


PTIME 


Returns time information on the current process. 


TTIME 


Returns time information on the current thread. 


PMEM 
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Returns the maximum memory (RSS) used by the current process. 


PRCVDSIG 


Returns the number of signals that have been received by the process. 


Return codes: 


* For PID, PPID or TID: an ID 
* For Windows PPRIO: "IDLE", "NORMAL", "HIGH", "REALTIME", or "UNKNOWN" 
* For Unix PPRIO: а number from -20 to +20. 


* For TPRIO: "IDLE", "LOWEST", "BELOW NORMAL", "NORMAL", "ABOVE_NORMAL", 
"HIGHEST", "TIME CRITICAL", or UNKNOWN" 
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* For Windows PTIME or TTIME: the creation date and time, the amount of time that the process 
executed in kernel mode, and the amount of time that the process executed in user mode 


* For Unix PTIME: the summary and the duration that the process executed in kernel mode, and the 
duration that the process executed in user mode 


8.54. SysQueryRexxMacro 


>>-SysQueryRexxMacro (name)------------------------------------- >< 


Queries the existence of a macrospace function. SysQueryRexxMacro returns the placement order of the 


пи 


macrospace function or a null string ("") if the function does not exist іп Ше macrospace. 


Parameter: 


name 


The name of a function in the Rexx macrospace. 


8.55. SysReleaseMutexSem 


»»-SysReleaseMutexSem(handle)---------------------------------- >< 


Releases a mutex semaphore. 


Parameter: 


handle 
A handle returned from a previous SysCreateMutexSem call. 


Return codes: 


0 
No errors. 
Other 
An error occurred. On Windows, a Windows System Error code is returned. This may be one of the 
following, but could be others. 
6 
Invalid handle. 
105 
Owner died. 
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288 


Not owner. 


8.56. SysReorderRexxMacro 


>>-SysReorderRexxMacro (name, order)----------------------------- >< 


Reorders a routine loaded in the Rexx macrospace. SysReorderRexxMacro returns the 
RexxReorderMacro return code. 


Parameters: 


name 


The name of a function in the macrospace. 


order 


The new macro search order. The order can be "B" (Before) or "A" (After). 


8.57. SysRequestMutexSem 


»»-SysRequestMutexSem(handle-4---------- %-)-------------------- >< 
+-,timeout-+ 


Requests a mutex semaphore. SysRequestMutexSem returns the WaitForSingleObject return code. 


Parameters: 


handle 


A handle returned from a previous SysCreateMutexSem call. 


timeout 
The time, in milliseconds, to wait on the semaphore. The default timeout is an infinite wait. 


Return codes: 


0 
No errors. 

Other 
An error occurred. On Windows, a Windows System Error code is returned. This may be one of the 
following, but could be others. 

6 


Invalid handle. 
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103 


Too many requests. 


121 


Error timeout. 


8.58. SysResetEventSem 


»»-SysResetEventSem(handle)------------------------------------ >< 


Resets an event semaphore.. 


Parameter: 


handle 
A handle returned from a previous SysCreateEventSem call. 


Return codes: 


0 
No errors. 

Other 
An error occurred. On Windows, a Windows System Error code is returned. This may be one of the 
following, but could be others. 

6 


Invalid handle. 


8.59. SysRmDir 


»»-SysRmDir(dirspec)------------------------------------------- >< 


Deletes a specified file directory without your confirmation. 


Parameter: 


dirspec 
The directory that should be deleted. 


Return codes: 


Directory removal was successful. 
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Other 


An error occurred. On Windows, a Windows System Error code is returned. This may be one of the 
following, but could be others. 


File not found. 


Path not found. 


Access denied or busy. 


16 


Current directory. 


26 
Not a DOS disk. 


32 


Sharing violation. 


108 
Drive locked. 


123 


Invalid name. 


145 


Directory not empty. 


146 
Is Subst Path. 


147 
Is Join Path. 


206 
File name exceeds range. 


Example: 


/* Code */ 
call SysRmDir "c:\rexx" 
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8.60. SysSaveRexxMacroSpace 


»»-SysSaveRexxMacroSpace(file)--------------------------------- >< 


Saves the Rexx macrospace. SysSaveRexxMacroSpace returns the RexxSaveMacroSpace return code. 


Parameter: 


file 


The file used to save the functions in the Rexx macrospace. 


8.61. SysSearchPath 


»»-SysSearchPath(path,filename-4----------- %-)----------------- >< 
+-,--option-+ 


Searches the specified file path for the specified file. If the file is found, the search returns the full file 
specification of the first file found within the path, and then stops searching. If the file is not found, the 
search returns a null string. 


Parameters: 


path 


An environment variable name. The environment variable must contain a list of file directories. 
Examples are "PATH" or "DPATH". 


filename 


The file for which the path is to be searched. 
option 


Specifies where the search starts. 


"С" 


Starts Ше search at the current directory and then along Ше specified path. This is Ше default. 


"N" 
Starts the search at the path, not at the current directory. 
Example: 
/* Code */ 


fspec = SysSearchPath("PATH", "CMD.EXE") 
say "CMD.EXE is located at" fspec 


/* Output */ 
CMD.EXE is located at C:\WIN\CMD.EXE 
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8.62. SysSetFileDateTime 


»»-SysSetFileDateTime(filename-4-------------------------------- %-)->< 
%-,--%--------- %--%------------ +-+ 


y 


+-newdate-+ +-,--newtime-+ 


Modifies the "Last Modified" date and time of file filename. If no new date or time is specified the file 
date or time is set to the current time (TOUCH). If only the date is omitted, the "Last Modified" date 
remains unchanged. If only the time is omitted, the "Last Modified" time remains unchanged. 


The filename can also be a directory name. 


The file that you want to change must not be opened by another process or must at least allow shared 
writes to update the time stamp. 


Parameters: 


filename 


The name of the file to be updated. 


newdate 


The new date for the file, to be specified in the format Y Y Y Y-MM-DD, where YYYY > 1800. 


newtime 
The new time for the file, to be specified in the format HH:MM:SS (24-hour format). 


Return codes: 


0 

The file date and time were updated correctly. 
-1 

The update of the file date or time failed. 
Example: 


Call SysSetFileDateTime "MyFile.Log" /ж touch file */ 

Call SysSetFileDateTime "MyFile.Log", "1998-12-17" 

Call SysSetFileDateTime "MyFile.Log", , "16:37:21" 

Call SysSetFileDateTime "MyFile.Log", "1998-12-17", "16:37:21" 


Call SysSetFileDateTime "C:\MyDir" /* touch dir on Windows NT */ 


8.63. SysSetPriority 


»»-SysSetPriority(class,delta)--------------------------------- >< 


Changes the priority of the current process. A return code of 0 indicates no error. 


Parameters: 
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class 


The new process priority class. The allowed classes are: 


0 or "IDLE" 


Idle time priority 
1 or "NORMAL" 
Regular priority 
2 or "HIGH" 
High or time-critical priority 


3 or "REALTIME" 


Real-time priority 


delta 


The change applied to the process priority level. delta must be in the range -15 to +15. It can also be 
a symbolic name: 


* "IDLE" for -15 

* "LOWEST' for -2 

* "BELOW NORMAL' for -1 
* "NORMAL" for 0 

* "ABOVE NORMAL" for 1 
* "HIGHEST" for 2 

* "TIME CRITICAL" for 15 


No errors. 


Other 


An error occurred. A Windows System Error code is returned. This may be one of the following, but 
could be others. 


307 


Invalid priority class. 


8.64. SysShutdownSystem (Windows only) 
»»-SysShutdownSystem(------------------------------------------- > 


"E +-)-->< 


482 ooRexx Reference Version 4.0.0 


Chapter 8. Rexx Utilities (RexxUtil) 


ж-сотприцек-ч------------<+-+-<-<-------<------<-+-+ << + 
#-шеззаре-1-------------------<--<- ---- + 
*t-,timeout-4--------------------- + 
+-,appclose-+--------- + 


+-,reboot-+ 


Shuts down the system. 


Parameters: 


computer 


пи 


Name of the remote machine. "" = local. 


message 


message for dialog. 


timeout 


Time to display message. 


appclose 


No dialog "save unsaved data". 


reboot 
1 to reboot the system. 
Returns: 


Returns 0 for success or a Windows System Error code for failure. 


8.65. SysSleep 


»»-SysSleep(secs)---------------------------------------------- >< 


Pauses a Rexx program for a specified time interval. 


Parameter: 


secs 


The number of seconds for which the program is to be paused. You can specify up to seven decimal 
places in the number. 


Example: 


Say "Now paused for 2 seconds 2 
Call SysSleep 2 
Say "Now paused for 0.1234567 seconds ..." 


Call SysSleep 0.1234567 


Call SysSleep 0.12345678 -- Error 40: Incorrect call to routine 


ooRexx Reference Version 4.0.0 483 


Chapter 8. Rexx Utilities (RexxUtil) 


8.66. SysStemCopy 


»»-SysStemCopy--(--fromstem--,--tostem-------------------------- ? 
>--%------------------------------------------------------------------ %--)->< 
%-,--%------ %--4------------------------------------------------- +-+ 
+-#гош-+  4-,--4----4--4---------------------------------- +-+ 
+-to-+ 4-,---------- +--+---------------- +-+ 
*-count-* +-,--"--+-Т-+--"-+ 
+-0-+ 


Copies items from Ше source stem to Ше target stem. Items in Ше source stem are copied starting at Ше 
from index (default is 1) into the target stem beginning at the to index (default is 1). The number of items 
to be copied to the target stem can be specified with the count. The default is to copy all items in the 
source stem. 


You can also specify that the items are to be inserted into the target stem at the position and the existing 
items are shifted to the end. 


This function operates only on stem arrays that specify the number of items in stem.0 and all items must 
be numbered from 1 to n without omitting an index. 


Parameters: 
fromstem 
The name of the source stem. 


tostem 


The name of the target stem. 


from 


The first index in the source stem to be copied. 


to 


The position at which the items are to be inserted in the target stem. 


count 


The number of items to be copied or inserted. 


insert 


Either of the following values: 


Insert items. 


Overwrite items. 


Return codes: 
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0 
The stem was copied successfully. 
-1 
Copying the stem failed. 
Example: 
Source.0 = 3 
Source.1 - "Hello" 
Source.2 - "from" 
Source.3 - "Rexx" 
Call SysStemCopy "Source.", "Target." 
Call SysStemCopy "Source.", "Target.", 1, 5, 2, "I" 


8.67. SysStemDelete 


»»-SysStemDelete(stem,startitem-4-------------- %-)------------- >< 
+-,--itemcount-+ 


Deletes the specified item at the index startitem in the stem. If more than one item is to be deleted the 
itemcount must be specified. After deleting the requested items the stem is compacted, which means that 
items following the deleted items are moved to the vacant positions. 


This function operates only on stem arrays that specify the number of items in stem.0 and all items must 
be numbered from 1 to n without omitting an index. 


Parameters: 


stem 


The name of the stem from which the item is to be deleted. 


startitem 


The index of the item to be deleted. 


itemcount 
The number of items to be deleted if more than one. 


Return codes: 


0 

Deleting was successful. 
-1 

Deleting failed. 
Example: 
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Call SysStemDelete "MyStem.", 5 
Call SysStemDelete "MyStem.", 5, 4 


8.68. SysStemlnsert 


>>-SysStemInsert (stem,position,value)-------------------------- >< 
Inserts a new item at position in the stem. All items in the stem following this position are shifted down 
by one position. 


This function operates only on stem arrays that specify the number of items in stem.0 and all items must 
be numbered from 1 to n without omitting an index. 


Parameters: 


stem 


The name of the stem in which an item is to be inserted. 
position 

The index at which the new item is to be inserted. 
value 


The value of the new item. 


Return codes: 


0 

Inserting was successful. 
-1 

Inserting failed. 
Example: 


Call SysStemInsert "MyStem.", 5, "New value for item 5" 


8.69. SysStemSort 


+-A-+ +-C-+ %-1----- + 
»»-SysStemSort--(--stem--,--"--4-D-4--"--,--"--4-I-4--"--,--*-start-4--» 
%-1-------- + 
»--,--end--,--*-firstcol-*--,--lastcol--)----------------------------- >< 


Sorts all or the specified items in the stem. The items can be sorted in ascending or descending order and 
the case of the strings being compared can be respected or ignored. Sorting can be further narrowed by 
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specifying the first and last item to be sorted or the columns used as sort keys. Because the sort uses a 
quick-sort algorithm, the order of sorted items according to the sort key is undetermined. 


This function operates only on stems that specify the number of items in stem.0 and all items must be 
numbered from | to n without omitting an index. A value of 0 in stem.0 is also valid but no sort will be 
performed. 


Parameters: 


stem 


The name of the stem to be sorted. 


order 


Either "A" for ascending or "D" for descending. The default is "A". 


type 
The type of comparison: either "C" for case or "I" for ignore. The default is "C". 


start 


The index at which the sort is to start. The default is 1. 


end 


The index at which the sort is to end. The default is the last item. 


firstcol 


The first column to be used as sort key. The default is 1. 


lastcol 
The last column to be used as sort key. The default is the last column. 


Return codes: 


0 

The sort was successful. 
-1 

The sort failed. 
Example: 


/* sort all elements descending, use cols 5 to 10 as key */ 
Call SysStemSort "MyStem.", "D", , , ,5, 10 


/* sort all elements ascending, ignore the case */ 
Call SysStemSort "MyStem.", "A", "I" 





/* sort elements 10 to 20 ascending, use cols 1 to 10 as key */ 
Call SysStemSort "MyStem.", , ,10, 20, 1, 10 
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8.70. SysSwitchSession (Windows only) 
»»-SysSwitchSession(name)-------------------------------------- >< 


Brings the named window to the foreground. Modern versions of Windows do not always allow a 
window to be brought to the foreground programmatically. Instead, the icon for the window on the task 
bar is set to flashing. 


Parameter: 


name 


The name of the window you want to be the foreground window. The name of the window must 
exactly match the title of the window, but is not case sensitive. The title of a window is the text 
displayed in its title bar. 


O is returned on success and a Windows System Error code on failure. 


8.71. SysSystemDirectory (Windows only) 


>>-SysSystemDirectory ()---------------------------------------- >< 


Returns the Windows system directory. 


8.72. SysTempFileName 


>>-SysTempFileName (template-+--------- %-)---------------------- >< 
+-,filter-+ 


Returns a unique name for a file or directory that does not currently exist. If an error occurs or 
SysTempFileName cannot create a unique name from the template, it returns a null string (""). 
SysTempFileName is useful when a program requires a temporary file. 


Parameters: 


template 


The location and base form of the temporary file or directory name. The template is a valid file or 
directory specification with up to five filter characters. 


SysTempFileName generates the filter character replacements with a random number algorithm. If 
the resulting file or directory already exists, SysTempFileName increments the replacement value 
until all possibilities have been exhausted. 


There are slight differences in how the template works on Windows and Unix/Linux. 


On Windows: The file name part of the template can be any length. However, the template must 
contain at least 1 filter character or the empty string is returned. The unique name is created solely 
by substituting random numbers for the filter character(s). If there is a directory name part of the 
template in addition to the file name part, and the directory name part contains a non-existent 
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directory, the function will succeed. However, the temporary file will not be writable unless the user 
first creates the non-existent directory, or directories. When the function succeeds, the result is 
always the same length as the template. 


On Unix/Linux: Only the first five characters of the file name part of the template are used. Any 
characters after the first five in the file name part are ignored. The unique name is generated by the 
operating system adding a random string of characaters to the end of the template. The template 
does not have to include any filter characters. If the template does include filter characters, then 
ooRexx replaces those filter characters with random numbers. Because the operating system adds a 
random string to the end of the template, the result will always be longer than the template. In 
general, if the template does not contain a directory part, or if the directory part is not writable by 
the user, a writable directory part is added by the operating system (most likely /tmp.) This last 
behavior may vary depending on the exact version of the Unix/Linux operating system. 


filter 


The filter character used in template. SysTempFileName replaces each filter character in template 
with a numeric value. The resulting string represents a file or directory that does not exist. The 
default filter character is ?. 


Examples: 


/* Windows Code */ 

say SysTempFileName("C:\TEMP\MYEXEC.???") 

say SysTempFileName("C:\TEMP\MYEXEC.tmp") -- produces the empty string. 
say SysTempFileName("C:\TEMP\??MYEXEC.???") 

say SysTempFileName("C:\MYEXEC@.@@@", "@") 


/* Output */ 
C:\TEMP\MYEXEC. 251 


С: \TEMP\10MYEXEC .392 
С: \MYEXEC6 .019 


/* Unix/Linux Code. mydir is an existing directory. */ 


say SysTempFileName("/mydir/MYEXEC.???") -- filter characters are ignored 
say SysTempFileName("/mydir/MYEXEC.tmp") -- produces a unique name 

say SysTempFileName("/mydir/??MYEXEC.???") 

say SysTempFileName("/bogusdir/??MYEXEC.???") 

say SysTempFileName("MYEXEC@.@@@", "@") 


/* Output */ 
/mydir/MYEXEYqY2Hd 
/mydir/MYEXET4dwdz 
/mydir/77MYELnIOIU 
/tmp/77MYEzjoweg 

/ tmp/MYEXEJN j3JB 
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8.73. SysTextScreenRead (Windows only) 


»»-SysTextScreenRead(-row,column--4------ %--)------------------ >< 
+-,len-+ 


Reads characters from a specified screen location. These include any carriage return and linefeed 
characters if the number of character reads spans multiple lines. 


Parameters: 


row 


The row from which to start reading. 


col 


The column from which to start reading. 


len 
The number of characters to read. The default is to read to the end of the screen. 
Note that, on error, a Windows System Error code is returned. 


Limitations: This function reads in only screen characters and does not consider the color attributes of 
each character read. When restoring a character string to the screen with SAY or the CHAROUT built-in 
function, the previous color settings are lost. 


Examples: 


/* Reading the entire screen */ 
screen = SysTextScreenRead(0, 0) 


/* Reading one line */ 
line = SysTextScreenRead(2, 0, 80) 


8.74. SysTextScreenSize (Windows only) 


»»-SysTextScreenSize()----------------------------------------- >< 


Returns the size of the screen in the format: row col. 


Example: 
/* Code */ 
call RxFuncAdd "SysTextScreenSize", "RexxUtil", "SysTextScreenSize" 


parse value SysTextScreenSize() with row col 
say "Rows="row", Columns="col 
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8.75. SysToUnicode (Windows only) 


>>-SysToUnicode--(--string, codepage, translateflags, outstem--)->< 


Maps a character string to a UNICODE string. 


Parameters: 


string 


A string containing the UNICODE characters to be mapped. 


codepage 


Specifies the code page used to perform the conversion. This parameter can be the value of any code 
page that is installed or available in the system. The default is the current original equipment 
manufacturer (OEM) code-page identifier for the system. 


You can also specify one of the following values: 


ACP 
ANSI code page. 


OEMCP 
OEM code page. 


SYMBOL 
Windows 2000: symbol code page. 


THREAD_ACP 
Windows 2000: current thread’s ANSI code page. 


UTF7 
Windows NT 4.0 and Windows 2000: translate using UTF-7. 


UTF8 


Windows NT 4.0 and Windows 2000: translate using UTF-8. When this is set, translateflags 
must be set. 


translateflags 


Indicates whether to translate to precomposed or composite-wide characters (if a composite form 
exists), whether to use glyph characters in place of control characters, and how to deal with invalid 
characters. 


You can specify a combination of the following flags: 
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PRECOMPOSED 
Always use precomposed characters, that is, characters in which a base character and a 
nonspacing character have a single character value. This is the default translation option. 
Cannot be used with COMPOSITE. 
COMPOSITE 
Always use composite characters, that is, characters in which a base character and a 
nonspacing character have different character values. Cannot be used with PRECOMPOSED. 
ERR_INVALID_CHARS 


If the function encounters an invalid input character, it fails and returns "1113". 


USEGLYPHCHARS 
Use glyph characters instead of control characters. 


A composite character consists of a base character and a nonspacing character, each having different 
character values. A precomposed character has a single character value for a base-nonspacing 
character combination. In the character е, the "e" is the base character and the "grave" accent mark 
is the nonspacing character. The function's default behavior is to translate to the precomposed form. 
If a precomposed form does not exist, the function attempts to translate to a composite form. 


The flags PRECOMPOSED and COMPOSITE are mutually exclusive. The USEGLYPHCHARS 
flag and the ERR INVALID CHARS can be set regardless of the state of the other flags. 


outstem 


The name of the stem variable that will contain the converted result. If the conversion was 
successful the stem will be composed of the following value(s): 


outstem. TEXT 


This variable will contain the converted string. 


Return codes: 


No errors. 


Other 


An error occurred. A Windows System Error code is returned. This may be one of the following, but 
could be others. 


87 


Incorrect code page or codepage value. 


1004 


Invalid translate flags. 
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1113 


No mapping for the Unicode character exists in the target code page. 


8.76. SysUtilVersion 


»»-SysUtilVersion()-------------------------------------------- >< 

Returns a version number that identifies the current level of the Rexx Utilities package. It can be used to 
verify the availability of certain functions. 

Return code: The REXXUTIL version number in the format n .mm. 

Examples: 


Because this function was not part of the original packaging, a sample logic to check for a certain level 
of RexxUTIL can look as follows: 


If RxFuncQuery("SysUtilVersion") = 1 |, 
SysUtilVersion() < "2.00" Then 
Say "Your RexxUTIL.DLL is not at the current level" 


If a specific function should be used that was added at a later REXXUTIL level a similar check can be 
performed by querying this function as follows: 


If RxFuncQuery("SysSetFileDateTime") = 1 Then 
Say "Your REXXUTIL.DLL is not at the current level" 


8.77. SysVersion 
»»-SysVersion()------------------------------------------------ >< 


Returns a string to identify the operating system and version. The first word of the returned string 
contains the identifier for the operating system and the rest of the string contains a operating specific 
version string. Something like: WindowsNT x or Linux x. 


Some possible output for operating systems supported by ooRexx might be: 


Say SysVersion() -» "Linux #1 SMP Mon Oct 16 14:54:20 EDT 2006.2.6.18-1.2798.fc6" 
Say SysVersion() -> "WindowsNT 5.00" 


Note: This function can be used to replace the operating-system-specific functions SysWinVer(), and 
SysLinVer(). 
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8.78. SysVolumeLabel (Windows only) 


>>-SysVolumeLabel (--+------------- %--)------------------------------ >< 
+-driveLetter-+ 


Returns the volume label for the specified drive. 


Parameter: 


driveLetter 
A drive letter in the form 'X:'. If the drive letter is omitted than the current drive is used. 


Return codes: 


0 
Encryption was successful. 
2 
File not found. 
4 
Cannot open file. 
5 
Access denied. 
82 


Cannot encrypt. 


8.79. SysWait (Unix only) 
»»-SysWait()--------------------------------------------------- >< 


Waits for all child processes to end. 
Returns: 

The exit code from the child process. 
Example: 


SysFork() has an example that uses wait (). 


8.80. SysWaitEventSem 


»»-SysWaitEventSem(handle-4---------- %-)----------------------- >< 
+-,timeout-+ 
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Waits on an event semaphore. SysWaitEventSem returns the WaitForSingleObject return code. 


Parameters: 


handle 


A handle returned from a previous SysCreateEventSem call. 


timeout 
The time, in milliseconds, to wait on the semaphore. The default timeout is an infinite wait. 


Return codes: 


0 
No errors. 
Other 
An error occurred. On Windows, a Windows System Error code is returned. This may be one of the 
following, but could be others. 
6 
Invalid handle. 
258 
Timeout. 


8.81. SysWaitNamedPipe (Windows only) 


»»-SysWaitNamedPipe (name-4---------- %-)------------------------ >< 
+-,timeout-+ 
Performs a timed wait on a named pipe and returns the WaitNamedPipe return code. 


Parameters: 


name 


The name of the pipe in the form "\\servername\pipe\pipename." 


timeout 


The number of microseconds to be waited. If you omit timeout or specify 0, SysWaitNamedPipe 
uses the default timeout value. To wait until the pipe is no longer busy, you can use a value of -1. 


Returns 0 on success. A Windows System Error code is returned on error. 
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8.82. SysWinDecryptFile (Windows only) 


»»-SysWinDecryptFile(filename)--------------------------------- >< 


Decrypts a given file (Windows 2000 only). 


Parameter: 


filename 
The file to be decrypted. 


Return codes: 


0 

Decryption was successful. 
Other 

A Windows System Error code. This may be one of the following, but could be others. 
2 

File not found. 
4 

Cannot open file. 
5 

Access denied. 
82 


Cannot decrypt. 


8.83. SysWinEncryptFile (Windows only) 


»»-SysWinEncryptFile(filename)--------------------------------- >< 


Encrypts a given file (Windows 2000 only). 


Parameter: 


filename 
The file to be encrypted. 


Return codes: 


Encryption was successful. 
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Other 


A Windows System Error code. This may be one of the following, but could be others. 


2 

File not found. 
4 

Cannot open file. 
5 

Access denied. 
82 


Cannot encrypt. 


8.84. SysWinGetDefaultPrinter (Windows only) 


>>-SysWinGetDefaultPrintern soo aa es >< 


1 


Returns the current default printer in the form "Printername,Drivername,Portname". 


8.85. SysWinGetPrinters (Windows only) 


»»-SysWinGetPrinters(stem.)------------------------------------ >< 
Fills a stem with the available printer descriptions. 
Parameters: 
stem.0 
The number of entries 


stem.i 
Entry 
Each entry is of the form "Printername,Drivername,Portname". 


Return codes: 


Success 
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Failure 


8.86. SysWinSetDefaultPrinter (Windows only) 


»»-SysWinSetDefaultPrinter(description)------------------------ >< 


Sets the default printer. 


Parameter: 


description 


A string identifying the printer. On Windows 2000 or later this string can be just the printer name. 
For earlier versions of Windows, the string must have the form 
"Printername,Drivername,Portname". 


Note: For Windows 2000 or later either form of the description string is accepted. However, using 
just the printer name is the preferred method. Using the "Printername,Drivername,Portname" 
form will invoke an outdated Windows API that Microsoft has deprecated. 


Return codes: 


Success 


non-zero 
A Windows System Error code. You can use SysGetErrortext() to get a description of the error. 


Example: 
/* set default printer */ 


default - SysWinGetDefaultPrinter() 
parse var default default",". 

say ’The Default printer is: default 
say 


if SysWinGetPrinters(list.) == 0 then do 
say "List of available printers (* = default):" 
do 151 to 11в%.0 
parse var list.i pname",". 
if pname -- default then 
say i list.i "x" 
else 
say i list.i 
end 
say 


498 ooRexx Reference Version 4.0.0 


Chapter 8. Rexx Utilities (RexxUtil) 


say "Please enter number of new default printer (0 = keep default)" 
pull i 


numberÜk = .false 


if i~datatype(’W’) then do 
if O <= i & i <= list.O then до 
numberOK = .true 


if i > 0 then до 
/* Assumes we are on Windows 2000 or later. */ 
parse var list.i pname",". 
ret = SysWinSetDefaultPrinter (pname) 
if ret <> 0 then do 
say "Error setting default printer ("ret"):" SysGetErrorText (ret) 
end 
else do 
say "The new default printer is:" pname 
end 
end 
end 
end 


if \ numberOk then до 
say "You did not enter a valid printer number." 
end 
end 
else do 
say "Failed to get a list of the available printers." 
end 


8.87. SysWinVer Windows only) 
»»-SysWinVer()------------------------------------------------- >< 


Returns a string specifying the Windows operating system version information in the form x. xx. 
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The parsing instructions are ARG, PARSE, and PULL (see ARG, PARSE, and PULL). 


The data to be parsed is a source string. Parsing splits the data in a source string and assigns pieces of it 
to the variables named in a template. A template is a model specifying how to split the source string. The 
simplest kind of template consists of a list of variable names. Here is an example: 


variable1 variable2 variable3 


This kind of template parses the source string into whitespace-delimited words. More complicated 
templates contain patterns in addition to variable names: 


String patterns 
Match the characters in the source string to specify where it is to be split. (See Templates 
Containing String Patterns for details.) 

Positional patterns 


Indicate the character positions at which the source string is to be split. (See Templates Containing 
Positional (Numeric) Patterns for details.) 


Parsing is essentially a two-step process: 


1. Parse the source string into appropriate substrings using patterns. 


2. Parse each substring into words. 


9.1. Simple Templates for Parsing into Words 
Here is a parsing instruction: 


parse value "time and tide" with vari var2 var3 


The template in this instruction is: var1 var2 var3. The data to be parsed is between the keywords 
PARSE VALUE and the keyword WITH, the source string time and tide. Parsing divides the source string 
into whitespace-delimited words and assigns them to the variables named in the template as follows: 


vari="time" 
var2="and" 


var3="tide" 


In this example, the source string to be parsed is a literal string, time and tide. In the next example, the 
source string is a variable. 


/* PARSE VALUE using a variable as the source string to parse ж/ 
string="time and tide" 
parse value string with vari var2 var3 /* same results */ 
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PARSE VALUE does not convert lowercase a-z in the source string to uppercase A-Z. If you want to 
convert characters to uppercase, use PARSE UPPER VALUE. See Using UPPER, LOWER, and 
CASELESS for a summary of the effect of parsing instructions on the case. 


Note that if you specify the CASELESS option on a PARSE instruction, the string comparisons during 
the scanning operation are made independently of the alphabetic case. That is, a letter in uppercase is 
equal to the same letter in lowercase. 


All of the parsing instructions assign the parts of a source string to the variables named in a template. 
There are various parsing instructions because of the differences in the nature or origin of source strings. 
For a summary of all the parsing instructions, see Parsing Instructions Summary. 


The PARSE VAR instruction is similar to PARSE VALUE except that the source string to be parsed is 
always a variable. In PARSE VAR, the name of the variable containing the source string follows the 
keywords PARSE VAR. In the next example, the variable stars contains the source string. The template is 


stari star2 star3. 


/* PARSE VAR example ж/ 
stars="Sirius Polaris Rigil" 

parse var stars starí star2 star3 /* stari-"Sirius" ж/ 
/* star2="Polaris" */ 

/* star3-"Rigil" ж/ 


All variables in a template receive new values. If there are more variables in the template than words in 
the source string, the leftover variables receive null (empty) values. This is true for the entire parsing: for 
parsing into words with simple templates and for parsing with templates containing patterns. Here is an 
example of parsing into words: 


/* More variables in template than (words in) the source string ж/ 
satellite-"moon" 

parse var satellite Earth Mercury /* Earth-"moon" ж/ 
/* Mercury="" */ 


If there are more words in the source string than variables in the template, the last variable in the 
template receives all leftover data. Here is an example: 


/* More (words in the) source string than variables in template ж/ 
satellites-"moon Io Europa Callisto..." 

parse var satellites Earth Jupiter /* Earth-"moon" ж/ 
/* Jupiter-"Io Europa Callisto..."*/ 


Parsing into words removes leading and trailing whitespace characters from each word before it is 
assigned to a variable. The exception to this is the word or group of words assigned to the last variable. 
The last variable in a template receives leftover data, preserving extra leading and trailing whitespace 
characters. Here is an example: 


/* Preserving extra blanks ж/ 
solar5="Mercury Venus Earth Mars Jupiter " 

parse var solarb5 vari var2 var3 var4 

/* vari ="Mercury" ж/ 
/ж var2 ="Venus" ж/ 
/ж var3 ="Earth" ж/ 
/ж var4 -" Mars Jupiter " ж/ 
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In the source string, Earth has two leading blanks. Parsing removes both of them (the word-separator 
blank and the extra blank) before assigning var3="Earth". Mars has three leading blanks. Parsing 
removes one word-separator blank and keeps the other two leading blanks. It also keeps all five blanks 
between Mars and Jupiter and both trailing blanks after Jupiter. 


Parsing removes no whitespace characters if the template contains only one variable. For example: 


parse value " Pluto " with vari /* vari-" Pluto "*/ 


9.1.1. Message Term Assignments 


In addition to assigning values to variables, the PARSE instruction also allows any message term value 
that can be used on the left side of an assignment instruction (See Assignments and Symbols). For 


example: 

/* Preserving extra blanks ж/ 
solar5="Mercury Venus Earth Mars Jupiter " 

d = .directory^new 

parse var ѕо1аг5 d^vari d^var2 d^var3 d^var4 

/* d^vari ="Mercury" ж/ 
/ж d^var2 ="Venus" ж/ 
/ж d^var3 ="Earth" ж/ 
/ж d~var4 =" Mars Jupiter " ж/ 


9.1.2. Тһе Period as a Placeholder 


A period in a template is a placeholder. It is used instead of a variable name, but it receives no data. It is 
useful as a "dummy variable" in a list of variables or to collect unwanted information at the end of a 
string. And it saves the overhead of unneeded variables. 


The period in the first example is a placeholder. Be sure to separate adjacent periods with whitespace; 
otherwise, an error results. 


/* Period as a placeholder ж/ 
stars="Arcturus Betelgeuse Sirius Rigil" 

parse var stars . . brightest . /* brightest-"Sirius" */ 
/* Alternative to period as placeholder ж/ 


stars="Arcturus Betelgeuse Sirius Rigil" 
parse var stars drop junk brightest rest /* brightest-"Sirius" ж/ 


9.2. Templates Containing String Patterns 


A string pattern matches characters in the source string to indicate where to split it. A string pattern can 
be either of the following: 
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Literal string pattern 


One or more characters within quotation marks. 


Variable string pattern 


A variable within parentheses with no plus (+), minus (-), or equal sign (=) before the left 
parenthesis. (See Parsing with Variable Patterns for details.) 


Here are two templates, a simple template and a template containing a literal string pattern: 


vari var2 /* simple template ж/ 
vari ", " var2 /* template with literal string pattern ж/ 
The literal string pattern is: ", ". This template puts characters: 


* From the start of the source string up to (but not including) the first character of the match (the 
comma) into vari 


* Starting with the character after the last character of the match (the character after the blank that 
follows the comma) and ending with the end of the string into var2 


A template with a string pattern can omit some of the data in a source string when assigning data to 
variables. The next two examples contrast simple templates with templates containing literal string 


patterns. 

/* Simple template ж/ 
name="Smith, John" 

parse var name 11 fn /* Assigns: ln-"Smith," */ 
/* fn="John" ж/ 


Notice that the comma remains (the variable 1n contains "Smith,"). In the next example the template is 


ln ", " fn. This removes the comma. 
/* Template with literal string pattern ж/ 
name="Smith, John" 
parse var name Іп ", " fn /* Assigns: ln-"Smith" ж/ 
/* fn-"John"  */ 
First, the language processor scans the source string for ", ". It splits the source string at that point. The 


variable 1n receives data starting with the first character of the source string and ending with the last 
character before the match. The variable £n receives data starting with the first character after the match 
and ending with the end of string. 


A template with a string pattern omits data in the source string that matches the pattern. (There is a 
special case (see Combining String and Positional Patterns) in which a template with a string pattern 
does not omit matching data in the source string.) The pattern ", " (with a blank) is used instead of " ," 
(no blank) because, without the blank in the pattern, the variable £n receives " John" (including a blank). 


If the source string does not contain a match for a string pattern, any variables preceding the unmatched 
string pattern get all the data in question. Any variables after that pattern receive the null string. 


A null string is never found. It always matches the end of the source string. 
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9.3. Templates Containing Positional (Numeric) Patterns 


A positional pattern is a number that identifies the character position at which the data in the source 
string is to be split. The number must be a whole number. 


An absolute positional pattern is: 


* А number with no plus (+) or minus (-) sign preceding it or with an equal sign (=) preceding it. 


* Ап expression in parentheses with an equal sign before the left parenthesis. (See Parsing with Variable 
Patterns for details on variable positional patterns.) 


The number specifies the absolute character position at which the source string is to be split. 


Here is a template with absolute positional patterns: 


variablei 11 variable2 21 variable3 


The numbers 11 and 21 are absolute positional patterns. The number 11 refers to the 11th position in the 
input string, 21 to the 21st position. This template puts characters: 


* 1 through 10 of the source string into variablei 
* 11 through 20 into variable2 
* 21 to the end into variable3 


Positional patterns are probably most useful for working with a file of records, such as: 


Character positions 
1 11 21 40 


Fields: | LASTNAME | FIRST PSEUDONYM End of 
record 


The following example uses this record structure: 


/* Parsing with absolute positional patterns in template ж/ 
record. 1="Clemens Samuel Mark Twain Б 

record. 2="Evans Mary Ann George Eliot Е 

record.3-"Munro H.H. Saki и 

do n-1 to 3 


parse var record.n lastname 11 firstname 21 pseudonym 
If lastname="Evans" & firstname="Mary Ann" then say "By George!" 
end /* Says "By George!" after record 2 ж/ 


The source string is split at character position 11 and at position 21. The language processor assigns 
characters | to 10 to lastname, characters 11 to 20 to firstname, and characters 21 to 40 to pseudonym. 


The template could have been: 


1 lastname 11 firstname 21 pseudonym 


instead of 


ooRexx Reference Version 4.0.0 505 


Chapter 9. Parsing 


lastname 11 firstname 21 pseudonym 


Specifying 1 is optional. 


Optionally, you can put an equal sign before a number in a template. An equal sign is the same as no 
sign before a number in a template. The number refers to a particular character position in the source 
string. These two templates are equal: 


lastname 11 first 21 pseudonym 
lastname =11 first =21 pseudonym 


A relative positional pattern is a number with a plus (+) or minus (-) sign preceding it. It can also be a 
variable within parentheses, with a plus (+) or minus (-) sign preceding the left parenthesis; for details 
see Parsing with Variable Patterns. 


The number specifies the relative character position at which the source string is to be split. The plus or 
minus indicates movement right or left, respectively, from the start of the string (for the first pattern) or 
from the position of the last match. The position of the last match is the first character of the last match. 
Here is the same example as for absolute positional patterns done with relative positional patterns: 


/* Parsing with relative positional patterns in template ж/ 
record. 1="Clemens Samuel Mark Twain " 
record.2-"Evans Mary Ann George Eliot " 
record. 3="Munro H.H. Saki Ы 
do п-1 to 3 

parse var record.n lastname +10 firstname + 10 pseudonym 

If lastname="Evans" & firstname="Mary Ann" then say "By George!" 


end /* same results ж/ 


Whitespace characters between the sign and the number are insignificant. Therefore, +10 and + 10 have 
the same meaning. Note that +0 is a valid relative positional pattern. 


Absolute and relative positional patterns are interchangeable except in the special case (Combining 
String and Positional Patterns) when a string pattern precedes a variable name and a positional pattern 
follows the variable name. The templates from the examples of absolute and relative positional patterns 
give the same results. 


(Implied 
starting 
point is 
position 


1) 


lastname 11 


lastname + 10 





Put characters 
1 through10 in 
lastname. 
(non-inclusive 
stopping point 
is 11 (1 10) 


firstname 21 


firstname + 10 





Put characters 
1 through10 in 
firstname. 

(non-inclusive 
stopping point 
is 21 (11 + 10) 


pseudonym 
pseudonym 





Put characters 


21 through end 
of string in 
pseudonym. 


With positional patterns, a matching operation can back up to an earlier position in the source string. 
Here is an example using absolute positional patterns: 


/* Backing up to an earlier position (with absolute positional) 


string="astronomers" 
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parse var string 2 vari 4 1 var2 2 4 var3 5 11 var4 
say string "study" vari||var2||var3||var4 
/* Displays: "astronomers study stars" ж/ 


The absolute positional pattern 1 backs up to the first character іп the source string. 


With relative positional patterns, a number preceded by a minus sign backs up to an earlier position. Here 
is the same example using relative positional patterns: 


/* Backing up to an earlier position (with relative positional) ж/ 
string-"astronomers" 

parse var string 2 vari +2 -3 var2 +1 +2 var3 +1 +6 var4 

say string "study" vari||var2||var3]|var4 /* same results ж/ 


In the previous example, the relative positional pattern -3 backs up to the first character in the source 
string. 


The templates in the previous two examples are equivalent. 





2 магі 4 1 var2 3 4 var3 5 11 var4 
2 var2 +2 -3 var2 +1 +2 var3 +1 +6 var4 
Startat Noninclusive Go to 1 Non- Go to 4 Goto 11 
2. stopping point (4-3=1). inclusive (2+2=4). (5+6=11). 
is 4 (2+2 = 4). stopping Noninclusive 
point is 2 stopping point 
(1+1=2). is 5 (4+1=5). 


You can use templates with positional patterns to make several assignments: 


/* Making several assignments ж/ 
books="Silas Marner, Felix Holt, Daniel Deronda, Middlemarch" 

parse var books 1 Eliot 1 Evans 

/* Assigns the (entire) value of books to Eliot and to Evans. ж/ 


А length positional pattern is a number with a (>) or (<) preceding it. It can also be an expression 
within parentheses, with a (>) or (<) preceding the left parenthesis; for details see Parsing with Variable 
Patterns. 


The number specifies the length at which the source string is to be split, relative to the current position.. 
The > or < indicates movement right or left, respectively, from the start of the string (for the first pattern) 
or from the position of the last match. The position of the last match is the first character of the last 
match. Here is the same example as for relative positional patterns done with length positional patterns: 


/* Parsing with relative positional patterns in template ж/ 
record. 1="Clemens Samuel Mark Twain " 

record.2-"Evans Mary Ann George Eliot " 

record. 3="Munro H.H. Saki Е 

do п=1 to 3 


parse var record.n lastname >10 firstname >10 pseudonym 
If lastname="Evans" & firstname="Mary Ann" then say "By George!" 
end /* same results ж/ 
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Whitespace characters between the trigger and the number are insignificant. Therefore, >10 and > 10 
have the same meaning. Note that >0 <0 and are valid length positional pattern. 


The > length pattern and the + relative positional pattern are interchangeable except in the special case 
of the value 0. A >0 pattern will split the string into a null string and leave the match position 
unchanged. This is particularly useful for parsing off length-qualified fields from a string. 


/* Parsing with length patterns in template */ 

line = "04Mark0005Twain" 

parse var line len +2 first >(len) len +2 middle >(len) len +2 last >(len) 
say """first'" "’middle’" "’last’"’ -- displays "Mark" "" "Twain" 


/* parsing with relative patterns only */ 
parse var line len +2 first +(len) len +2 middle +(len) len +2 last +(len) 
say ’"?first’" "’middle’" "’last’"’ -- displays "Mark" "O5Twain" "Twain" 


The < length pattern will move the position the indicated position to the left, and split the string between 
the original position and the movement position. At of the operation, the current position is returned to 
the original position. This movement is equivalent to using a negative relative pattern followed by a 
positive relative pattern for the same length. This operation allows for easy extraction of characters that 
precede a string match. 


/* Parsing with length patterns in template */ 
parse value ’12345.6789’ with ’.’ digit <1 -- digit -> "5" 


/* parsing with relative patterns only */ 
parse value ’12345.6789’ with ’.’ -1 digit +1 -- digit -> "5" 


9.3.1. Combining Patterns and Parsing into Words 


If a template contains patterns that divide the source string into sections containing several words, string 
and positional patterns divide the source string into substrings. The language processor then applies a 
section of the template to each substring, following the rules for parsing into words. 


/* Combining string pattern and parsing into words ж/ 
name=" John Q. Public" 

parse var name fn init "." а /* Assigns: fn="John" ж/ 
/ж init=" q" */ 
/* ln-" Public" ж/ 


The pattern divides the template into two sections: 


* fn init 
е 11 


The matching pattern splits the source string into two substrings: 


" John g! 
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Е Public" 
The language processor parses these substrings into words based on the appropriate template section. 


John has three leading blanks. All are removed because parsing into words removes leading and trailing 
blanks except from the last variable. 


Q has six leading blanks. Parsing removes one word-separator blank and keeps the rest because init is 
the last variable in that section of the template. 


For the substring " Public", parsing assigns the entire string into 1n without removing any blanks. This 
is because 1n is the only variable in this section of the template. (For details about treatment of 
whitespace characters, see Simple Templates for Parsing into Words.) 


/* Combining positional patterns with parsing into words ж/ 
string-"R E X X" 
parse var string vari var2 4 var3 6 var4 /ж Assigns: vari-"R" ж/ 


/* var2="E" ж/ 
/ж var3="_X" ж/ 
/ж уаг4<" X" ж/ 


The pattern divides Ше template into three sections: 


e таг! таг2 
* var3 
* var4 


The matching patterns split the source string into three substrings that are individually parsed into words: 


6 "R E" 
e" yu 
e" y" 


The variable var1 receives "R"; var2 receives "E". Both var3 and var4 receive " X" (with a blank before 
the X) because each is the only variable in its section of the template. (For details on treatment of 
whitespace characters, see Simple Templates for Parsing into Words.) 


9.4. Parsing with Variable Patterns 


You might want to specify a pattern by using the value of a variable or expression instead of a fixed string 
or number. You do this by placing an expression in parentheses. This is a variable reference. Whitespace 
characters are not necessary inside or outside the parentheses, but you can add them if you wish. 


The template in the next parsing instruction contains the following literal string pattern ". ". 
parse var name fn init ". " Іа 
Here is how to specify that pattern as a variable string pattern: 


strngptrn-". " 
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parse var name fn init (strngptrn) 1n 


If no equal, plus sign, minus sign, >, or < precedes the parenthesis that is before the variable name, the 
character string value of the variable is then treated as a string pattern. The expression can reference 
variables that have been set earlier in the same template. 


Example: 
/* Using a variable as a string pattern ж/ 
/ж Тһе variable (delim) is set іп the same template */ 
SAY "Enter a date (mm/dd/yy format). =====> " /* assume 11/15/98 ж/ 
pull date 


parse var date month 3 delim +1 day +2 (delim) year 
/* Sets: month="11"; delim-"/"; day="15"; year-"98" ж/ 


If an equal, a plus, a minus sign, > or < precedes the left parenthesis, the value of the expression is 
treated as an absolute, relative positional, or length positional pattern. The value of the expression must 
be a positive whole number or zero. 


The expression can reference variables that have has been set earlier in the same template. In the 
following example, the first two fields specify the starting-character positions of the last two fields. 


Example: 
/* Using a variable as a positional pattern ж/ 
dataline = "12 26 ..... Samuel ClemensMark Twain" 


parse var dataline posi pos2 6 -(ров1) realname -(pos2) pseudonym 
/* Assigns: realname-"Samuel Clemens"; pseudonym="Mark Twain" ж/ 


The positional pattern 6 is needed in the template for the following reason: Word parsing occurs after the 
language processor divides the source string into substrings using patterns. Therefore, the positional 
pattern -(ров1) cannot be correctly interpreted as =12 until after the language processor has split the 
string at column 6 and assigned the blank-delimited words 12 and 26 to posi and pos2, respectively. 


9.5. Using UPPER, LOWER, and CASELESS 


Specifying UPPER on any of the PARSE instructions converts lowercase a-z to uppercase A-Z before 
parsing. 


The ARG instruction is a short form of PARSE UPPER ARG. The PULL instruction is a short form of 
PARSE UPPER PULL. If you do not desire uppercase translation, use PARSE ARG instead of ARG or 
PARSE UPPER ARG, and PARSE PULL instead of PULL or PARSE UPPER PULL. 


Specifying LOWER on any of the PARSE instructions converts uppercase A-Z to lowercase a-z before 
parsing. 


Specifying CASELESS means the comparisons during parsing are independent of the case--that is, a 
letter in uppercase is equal to the same letter in lowercase. 
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9.6. Parsing Instructions Summary 


All parsing instructions assign parts of the source string to the variables named in the template. The 
following table summarizes where the source string comes from. 


Table 9-1. Parsing Source Strings 

















Instruction Where the source string comes from 

ARG Arguments you list when you call the program or 
arguments in the call to a subroutine or function. 

PARSE ARG Arguments you list when you call the program or 
arguments in the call to a subroutine or function. 

PARSE LINEIN Next line in the default input stream. 

PULL The string at the head of the external data queue. 


(If the queue is empty, it uses default input, 
typically the terminal.) 

PARSE PULL The string at the head of the external data queue. 
(If the queue is empty, it uses default input, 
typically the terminal.) 

















PARSE SOURCE System-supplied string giving information about 
the executing program. 

PARSE VALUE Expression between the keywords VALUE and 
WITH in the instruction. 

PARSE VAR name Parses the value of name. 

PARSE VERSION System-supplied string specifying the language, 








language level, and (three-word) date. 





9.7. Parsing Instructions Examples 


All examples in this section parse source strings into words. 


ARG 

/* ARG with source string named in Rexx program invocation ж/ 
/* Program name із PALETTE. Specify 2 primary colors (yellow, ж/ 
/* red, blue) on call. Assume call is: palette red blue ж/ 
arg vari var2 /* Assigns: var1="RED"; var2="BLUE" */ 


If vari<>"RED" 6 var1<>"YELLOW" & vari<>"BLUE" then signal err 
If var2<>"RED" & var2<>"YELLOW" & var2<>"BLUE" then signal err 
total=length(var1)+length(var2) 
SELECT ; 

When total=7 then new="purple" 

When total=9 then new="orange" 

When total=10 then new="green" 
Otherwise пеи-таг1 /* entered duplicates */ 
END 
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Say new; exit /* Displays: "purple" ж/ 
Err: 
say 'Input error--color is not "red" or "blue" or "yellow"'; exit 


ARG converts alphabetic characters to uppercase before parsing. An example of ARG with the 
arguments in the CALL to a subroutine is in Parsing Several Strings. 


PARSE ARG is similar to ARG except that PARSE ARG does not convert alphabetic characters to 
uppercase before parsing. 


PARSE LINEIN 

parse linein "а=" numi "c=" num2 /* Assume: 8 and 9 ж/ 

sum=numi+num2 /* Enter: a=8 b-9 as input ж/ 

say sum /* Displays: "17" ж/ 

PARSE PULL 

PUSH "80 7" /* Puts data on queue ж/ 

parse pull fourscore seven /* Assigns: fourscore="80"; seven="7" ж/ 

SAY fourscore+seven /* Displays: "87" ж/ 

PARSE SOURCE 

parse source sysname . 

Say sysname /* Possibly Displays: ж/ 
/* "Windows" ж/ 

PARSE VALUE. 


PARSE VAR examples are throughout the chapter, starting with Parsing. 
PARSE VERSION 


parse version . level . 
say level /* Displays: "6.02" */ 


PULL is similar to PARSE PULL except that PULL converts alphabetic characters to uppercase before 
parsing. 


9.8. Advanced Topics in Parsing 


This section includes parsing several strings and flow charts illustrating a conceptual view of parsing. 


9.8.1. Parsing Several Strings 


Only ARG and PARSE ARG can have more than one source string. To parse several strings, you can 
specify several comma-separated templates. Here is an example: 


parse arg templatei, template2, template3 
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This instruction consists of the keywords PARSE ARG and three comma-separated templates. For an 
ARG instruction, the source strings to be parsed come from arguments you specify when you call a 
program or CALL a subroutine or function. Each comma is an instruction to the parser to move on to the 
next string. 


Example: 
/* Parsing several strings in a subroutine ж/ 


num="3" 
musketeers="Porthos Athos Aramis D'Artagnan" 


CALL Sub num,musketeers /* Passes num and musketeers to sub ж/ 
SAY total; say fourth /* Displays: "4" and " D'Artagnan" ж/ 
ЕХІТ 
Sub: 

parse arg subtotal, . . . fourth 

total=subtotal+1 

RETURN 


Note that when a Rexx program is started as a command, only one argument string is recognized. You 
can pass several argument strings for parsing if: 


* One Rexx program calls another Rexx program with the CALL instruction or a function call 
* Programs written in other languages start a Rexx program 


If there are more templates than source strings, each variable in a leftover template receives a null string. 
If there are more source strings than templates, the language processor ignores leftover source strings. If 
a template is empty (two subsequent commas) or contains no variable names, parsing proceeds to the 
next template and source string. 


9.8.2. Combining String and Positional Patterns 


There is a special case in which absolute and relative positional patterns do not work identically. Parsing 
with a template containing a string pattern skips the data in the source string that matches the pattern (see 
Templates Containing String Patterns). But a template containing the sequence string pattern, variable 
name, and relative position pattern does not skip the matching data. A relative positional pattern moves 
relative to the first character matching a string pattern. As a result, assignment includes the data in the 
source string that matches the string pattern. 


/* Template containing string pattern, then variable name, then ж/ 
/* relative positional pattern does not skip any data. ж/ 
string="REstructured eXtended eXecutor" 

parse var string vari 3 junk "X" var2 +1 junk "X" var3 +1 junk 

say vari||var2||var3 /ж Concatenates variables; displays: "Rexx" */ 


Here is how this template works: 
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уап 3 | | junk 'Х' | | var2 +1 | | jun X | | va +1 | | junk | 


Put 
characters 
1 through 1 
in var1 
(stopping 
point is 3). 


vari -RE 


Starting 
point at 3, 
put 
characters 
upto (not 
including) 
first 'X' in 
junk. 


junk= 


‘structured e' 


Starting 
with first 'X' 
put 1 (+1) 
character in 
var2. 


уаг2-Х! 


Starting 
with 
character 
after first 

'X' put up to 
second 'X' 
in junk. 


junk= 
‘tended e' 


9.8.3. Conceptual Overview of Parsing 


The following figures are to help you understand the concept of parsing. 


The figures include the following terms: 


string start 


is the beginning of the source string (or substring). 


string end 


is the end of the source string (or substring). 


length 


is the length of the source string. 


match start 


is in the source string and is the first character of the match. 


match end 


Starting 
with 
second 'X' 
put 1 (+1) 
character in 
var. 


var32'X' 


Starting 
with 
character 
after 
second 'X' 
put rest in 
junk. 


junk= 
'ecutor' 


is in the source string. For a string pattern, it is the first character after the end of the match. For a 
positional pattern, it is the same as match start. 


match position 


is in the source string. For a string pattern, it is the first matching character. For a positional pattern, 
it is the position of the matching character. 


token 


is a distinct syntactic element in a template, such as a variable, a period, a pattern, or a comma. 


value 


is the numeric value of a positional pattern. This can be either a constant or the resolved value of a 


variable. 
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Figure 9-1. Conceptual Overview of Parsing 


START 
Token is first one in template. 
Length=length(source string) 


Match start=1 
Match end=1 















End of template? 

no 
CALL Find Next Pattern. 
CALL Word Parsing. 
Skip to next token. 

no 


Parsing complete. 






Set next source string 
and template. 
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Figure 9-2. Conceptual View of Finding Next Pattern 


START: YES) String start=match end 
End of template? 


Match start=length + 1 
Match end=length + 1 
Return 


yes 


Token period, variable, 
or message term? 


Step to next token 


R ^ String start= match start 
Variable form? аа Match start=min(length + 1, 
match start + value) 
Match end=match start 





Token a plus or a “>”? 







Return 


yes YES! nesolve String start= match start 
Token a minus? Variable form? is valia Match start=max(1, match 
Start - value) 
Match end=match start 
no Return 


yes String start= match end 


yes 
Token an equal? Variable form? acm Match start=min(length + 1, 
its value 
value) 
Match end=match start 


Return 

yes String start» max(1, 

Token ап “< Variable form? = a match start - value) 
E 5 Return 


String start=match end 
Match start=min(length + 1, value) 
Match end=match start 


"e 
no 
no Return 
no 






Token a literal string? 


Token a variable 


String start=match end 

Match start=match position 

Match end=match position + 
pattern length 

Return 


Resolve Match found in 
its value rest of string? 


string? 





no 


Match зайлетот + 1 сад 
Match end=length + 1 String start- match end 


Match start= length + 1 
Match end=length + 1 
Return 


Return 
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Figure 9-3. Conceptual View of Word Parsing 


START: no ee 
Match end of string start? String end=match start 


yes 


String end=length + 1 


Substring=substr(source string, string start, (string end — string start)) 


Token=previous pattern 
















Any more tokens? 
Step to next token? 


Token variable, message 
term, or period? 


yes 


Any more tokens? 


yes 


Next token a variable, 


message term, or period? 





es 











Any substring left? 


no 

— pe. | Assign null string 
Strip any leading blanks 
Any substring left? 


yes 


Assign null string 
no 
Assign rest of substring 


Assign word from substring and step past blank 









Blank found in substring? 
yes 





Note: The figures do not include error cases. 
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Chapter 10. Numbers and Arithmetic 


This chapter gives an overview of the arithmetic facilities of the Rexx language. 


Numbers can be expressed flexibly. Leading and trailing whitespace characters are permitted, and 
exponential notation can be used. Valid numbers are, for example: 


12 /* a whole number */ 
"-76" /ж a signed whole number */ 
12.76 /* decimal places ж/ 
"+ 0.003" /ж blanks around the sign and so forth */ 
17. /ж ваше ав 17 ж/ 
25 /ж same as 0.5 */ 
4E9 /* exponential notation ж/ 
0.73e-7 /* exponential notation ж/ 


А number іп Rexx is defined as follows: 


>>-%------------ %Ж--4---------------------- *--t-digits-------- %---------- > 
+-whitespace-+  t-sign--t------------ +-+ +-digits.digits-+ 
+-whitespace-+ += digits------- + 
+-digits.------- + 
>--%------------ %-------------------------------------------------- >< 


+-whitespace-+ 


whitespace 


are one or more blanks or horizontal tab characters. 
sign 

is either + or -. 
digits 

are one or more of the decimal digits 0-9. 
Note that a single period alone is not a valid number. 


The arithmetic operators include addition (+), subtraction (-), multiplication (ж), power (жж), division 
(/), prefix plus (+), and prefix minus (-). In addition, it includes integer divide (4), which divides and 
returns the integer part, and remainder (//), which divides and returns the remainder. For examples of the 
arithmetic operators, see Operator Examples. 


The result of an arithmetic operation is formatted as a character string according to specific rules. The 
most important rules are: 


* Results are calculated up to a maximum number of significant digits. The default is 9, but can be 
overridden on a source-file basis with the ::OPTIONS directive. 19 for 64-bit systems, The default 
setting can be altered with the NUMERIC DIGITS instruction. Thus, with NUMERIC DIGITS 9, if a 
result requires more than 9 digits, it is rounded to 9 digits. For example, the division of 2 by 3 results 
in 0.666666667. 
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* Except for division and power, trailing zeros are preserved. For example: 


2.40 + 2 -> 4.40 
2.40 - 2 -> 0.40 
2.40 * 2 -> 4.80 
2.40 / 2 -> 1.2 


If necessary, you сап remove trailing zeros with the STRIP method (see STRIP), the STRIP function 
(see STRIP), or by division by 1. 


* А zero result is always expressed as the single digit 0. 


* Exponential form is used for a result depending on its value and the setting of NUMERIC DIGITS. If 
the number of places needed before the decimal point exceeds the NUMERIC DIGITS setting, or the 
number of places after the point exceeds twice the NUMERIC DIGITS setting, the number is 
expressed in exponential notation: 


1e6 * 1e6 -> 1E+12 /* not 1000000000000 */ 
1 / 3E10 -> 3.33333333E-11 /ж not 0.0000000000333333333 ж/ 


10.1. Precision 


Precision is the maximum number of significant digits that can result from an operation. This is 
controlled by the instruction: 


>>-NUMERIC DIGITS--4------------ L тт нняяня- ня >< 
+-expression-+ 


The expression is evaluated and must result in a positive whole number. This defines the precision 
(number of significant digits) of a calculation. Results are rounded to that precision, if necessary. 


If you do not specify expression in this instruction, or if no NUMERIC DIGITS instruction has been 
processed since the start of a program, the default precision is used. The Rexx standard for the default 
precision is 9. The default may be overridden on a source-file basis using the ::OPTIONS directive. 


NUMERIC DIGITS can set values smaller than nine. However, use small values with care because the 
loss of precision and rounding affects all Rexx computations, including, for example, the computation of 
new values for the control variable in DO loops. 


10.2. Arithmetic Operators 


Rexx arithmetic is performed by the operators +, -, ж, /, 7, //, and жж (add, subtract, multiply, divide, 
integer divide, remainder, and power). 


Before every arithmetic operation, the terms operated upon have leading zeros removed (noting the 
position of any decimal point, and leaving only one zero if all the digits in the number are zeros). They 
are then truncated, if necessary, to DIGITS + 1 significant digits before being used in the computation. 
The extra digit improves accuracy because it is inspected at the end of an operation, when a number is 
rounded to the required precision. When a number is truncated, the LOSTDIGITS condition is raised if a 
SIGNAL ON LOSTDIGITS condition trap is active. The operation is then carried out under up to double 
that precision. When the operation is completed, the result is rounded, if necessary, to the precision 
specified by the NUMERIC DIGITS instruction. 
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The values are rounded as follows: 5 through 9 are rounded up, and 0 through 4 are rounded down. 


10.2.1. Power 


The ** (power) operator raises a number to a power, which can be positive, negative, or 0. The power 
must be a whole number. The second term in the operation must be a whole number and is rounded to 
DIGITS digits, if necessary, as described under Limits and Errors when Rexx Uses Numbers Directly. If 
negative, the absolute value of the power is used, and the result is inverted (that is, the number 1 is 
divided by the result). For calculating the power, the number is multiplied by itself for the number of 
times expressed by the power. Trailing zeros are then removed as though the result were divided by 1. 


10.2.2. Integer Division 


The % (integer divide) operator divides two numbers and returns the integer part of the result. The result 
is calculated by repeatedly subtracting the divisor from the dividend as long as the dividend is larger than 
the divisor. During this subtraction, the absolute values of both the dividend and the divisor are used: the 
sign of the final result is the same as that which would result from regular division. 


If the result cannot be expressed as a whole number, the operation is in error and fails--that is, the result 
must not have more digits than the current setting of NUMERIC DIGITS. For example, 10000000000%3 
requires 10 digits for the result (3333333333) and would, therefore, fail if NUMERIC DIGITS 9 were in 
effect. 


10.2.3. Remainder 


The // (remainder) operator returns the remainder from an integer division and is defined to be the 
residue of the dividend after integer division. The sign of the remainder, if nonzero, is the same as that of 
the original dividend. 


This operation fails under the same conditions as integer division, that is, if integer division on the same 
two terms fails, the remainder cannot be calculated. 


10.2.4. Operator Examples 


/* With: NUMERIC DIGITS 5 */ 


1247.00 -> 19.00 
1.3-1.07 -> 0.23 
1.3-2.07 -> -0.77 
1.20ж3 -> 3.60 
T*3 -> 21 
0.9*0.8 -> 0.72 
1/3 -> 0.33333 
2/3 -> 0.66667 
5/2 -> 2.5 
1/10 -> 0.1 
12/12 -> 1 
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8.0/2 -» 4 
2**3 -> 8 
2жж-3 -> 0.125 
1.7жж8 -> 69.758 
2/3 -> 0 
2.1//3 -> 2.1 
10%3 -> 3 
10//3 -> 1 
-10//3 -> -1 
10.2//1 -> 0.2 
10//0.3 -> 0.1 
3.6//1.3 -> 1.0 


10.3. Exponential Notation 
For both large and small numbers, an exponential notation can be useful. For example: 


numeric digits 5 
say 54321*54321 


would display 2950800000 in the long form. Because this is misleading, the result is expressed as 
2.9508E+9 instead. 


The definition of numbers is, therefore, extended as follows: 


>>-+------------ %--%---------------------- *--t-digits-------- %---------- > 
+-whitespace-+ +-5ірп--+------------ +-+ +-digits.digits-+ 
+-whitespace-+ +-.digits------- + 
+-digits.------- + 
>--+--------------------- +--+------------ %------------------------- >< 
+-E--+------+--digits-+ +-whitespace-+ 
+-sign-+ 


The integer following the E represents a power of ten that is to be applied to the number. The E can be in 
uppercase or lowercase. 


Certain character strings are numbers even though they do not appear to be numeric, such as 0E123 (0 
raised to the 123 power) and 1E342 (1 raised to the 342 power). Also, a comparison such as 0E123-0E567 
gives a true result of 1 (0 is equal to 0). To prevent problems when comparing nonnumeric strings, use 
the strict comparison operators. 


Here are some examples: 


12E7 = 120000000 /* Displays "1" */ 
12E-5 = 0.00012 /* Displays "1" */ 
-12e4 = -120000 /* Displays "1" */ 
0e123 = 0e456 /* Displays "1" */ 
0e123 == (0е456 /* Displays "0" */ 
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The results of calculations are returned in either conventional or exponential form, depending on the 
setting of NUMERIC DIGITS. If the number of places needed before the decimal point exceeds 
DIGITS, or the number of places after the point exceeds twice DIGITS, the exponential form is used. 
The exponential form the language processor generates always has a sign following the E to improve 
readability. If the exponent is 0, the exponential part is omitted--that is, an exponential part of E+0 is not 
generated. 


You can explicitly convert numbers to exponential form, or force them to be displayed in the long form, 
by using the FORMAT built-in function (see FORMAT). 


Scientific notation is a form of exponential notation that adjusts the power of ten so that the number 
contains only one nonzero digit before the decimal point. Engineering notation is a form of exponential 
notation in which up to three digits appear before the decimal point, and the power of ten is always a 
multiple of three. The integer part can, therefore, range from 1 through 999. You can control whether 
scientific or engineering notation is used with the following instruction: 


+-SCIENTIFIC------------ + 
>>-NUMERIC ЕОВМ--%----------------------- Sa ta a ----< >< 
+-ENGINEERING----------- + 
Sa ae +--expression-+ 
+-VALUE-+ 


Scientific notation is the default. 


/* after the instruction ж/ 
Numeric form scientific 


123.45 ж 1611 -> 1.2345Е+13 


/* after the instruction */ 
Numeric form engineering 


123.45 ж 1е11 -> 12.345E+12 


10.4. Numeric Comparisons 


The comparison operators are listed in Comparison. You can use any of them for comparing numeric 


strings. However, you should not use ==, \==, ===, >>, \>>, =>>, <<, \<<, and =<< for comparing 
numbers because leading and trailing whitespace characters and leading zeros are significant with these 
operators. 


Numeric values are compared by subtracting the two numbers (calculating the difference) and then 
comparing the result with 0. That is, the operation: 


A? Z 
where ? is any numeric comparison operator, is identical with: 


(A а 7) ? "о" 
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It is, therefore, the difference between two numbers, when subtracted under Rexx subtraction rules, that 
determines their equality. 


Fuzz affects the comparison of two numbers. It controls how much two numbers can differ and still be 
considered equal in a comparison. The FUZZ value is set by the following instruction: 


>>-NUMERIC FUZZ--+------------ %--;----------------------------- >< 
+-expression-+ 
expression must result in a positive whole number or zero. The default is 0. 


Fuzz is to temporarily reduce the value of DIGITS. That is, the numbers are subtracted with a precision 
of DIGITS minus FUZZ digits during the comparison. The FUZZ setting must always be less than 
DIGITS. 


If, for example, DIGITS = 9 and FUZZ = 1, the comparison is carried out to 8 significant digits, just as 
though NUMERIC DIGITS 8 had been put in effect for the duration of the operation. 


Example: 


Numeric digits 5 
Numeric fuzz 0 


say 4.9999 = Б /* Displays "0" ж/ 
вау 4.9999 < Б /ж Півріаув "1" ж/ 
Numeric fuzz 1 

say 4.9999 =5 /* Displays "1" ж/ 
вау 4.9999 < Б /* Displays "0" ж/ 


10.5. Limits and Errors when Rexx Uses Numbers 
Directly 


When Rexx uses numbers directly, that is, numbers that have not been involved in an arithmetic 
operation, they are rounded, if necessary, according to the setting of NUMERIC DIGITS. The normal 
whole number limit depends on the platform default NUMERIC DIGITS setting. If the default setting is 
9, the whole number limit is 999999999. If the default DIGITS value is 18, the whole number limit is 
999999999999999909. 


The following table shows which numbers must Бе whole numbers and what their limits are: 


Table 10-1. Whole Number Limits 

















Power values (right-hand operand of the power The platform whole number limit. 

operator) 

Values of exprr and exprf in the DO instruction The platform whole number limit 

Values given for DIGITS or FUZZ in the The platform whole number limits (Note: FUZZ 
NUMERIC instruction must always be less than DIGITS.) 

Positional patterns in parsing templates The platform whole number limit 

Number given for option in the TRACE instruction | The platform whole number limit 
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When Rexx uses numbers directly, the following types of errors can occur: 


* Overflow or underflow. 


This error occurs if the exponential part of a result exceeds the range that the language processor can 
handle, when the result is formatted according to the current settings of NUMERIC DIGITS and 
NUMERIC FORM. The language defines a minimum capability for the exponential part, namely the 
largest number that can be expressed as an exact integer in default precision. Because the default 
precision is 9, you can use exponents in the range -999999999 through 999999999. 


Because this allows for (very) large exponents, overflow or underflow is treated as a syntax error. 
* Insufficient storage. 


Storage is needed for calculations and intermediate results, and if an arithmetic operation fails because 
of lack of storage. This is considered as a terminating error. 
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A condition is an event or state that CALL ON or SIGNAL ON can trap. A condition trap can modify the 
flow of execution in a Rexx program. Condition traps are turned on or off using the ON or OFF 
subkeywords of the SIGNAL and CALL instructions (see CALL and SIGNAL). 


>>-%-САШ.---%--------------------------------------------------- > 
+-SIGNAL-+ 

>--+-OFF--+-condition----------- +---в--------- Se aa >< 
| +-USER--usercondition-+ 
%-0М--%-соп4і%іоп----------- D +-+ 


+-USER--usercondition-+ +-NAME--trapname-+ 


condition, usercondition, and trapname are single symbols that are taken as constants. Following one of 
these instructions, a condition trap is set to either ON (enabled) or OFF (disabled). The initial setting for 
all condition traps is OFF. 


If a condition trap is enabled and the specified condition or usercondition occurs, control passes to the 
routine or label trapname if you have specified trapname. Otherwise, control passes to the routine or 
label usercondition or condition. CALL or SIGNAL is used, depending on whether the most recent trap 
for the condition was set using CALL ON or SIGNAL ON, respectively. 


Note: If you use CALL, the trapname can be an internal label, a built-in function, or an external 
routine. If you use SIGNAL, the trapname can only be an internal label. 


The conditions and their corresponding events that can be trapped are: 


ANY 


traps any condition that a more specific condition trap does not trap. For example, if NOVALUE is 
raised and there is no NOVALUE trap enabled, but there is a SIGNAL ON ANY trap, the ANY trap 
is called for the NOVALUE condition. For example, a CALL ON ANY trap is ignored if 
NOVALUE is raised because CALL ON NOVALUE is not allowed. 

ERROR 


raised if a command indicates an error condition upon return. It is also raised if any command 
indicates failure and none of the following is active: 


* CALL ON FAILURE 

* SIGNAL ON FAILURE 
* CALL ON ANY 

* SIGNAL ON ANY 


The condition is raised at the end of the clause that called the command but is ignored if the 
ERROR condition trap is already in the delayed state. The delayed state is the state of a condition 
trap when the condition has been raised but the trap has not yet been reset to the enabled (ON) or 
disabled (OFF) state. 
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FAILURE 


raised if a command indicates a failure condition upon return. The condition is raised at the end of 
the clause that called the command but is ignored if the FAILURE condition trap is already in the 
delayed state. 


An attempt to enter a command to an unknown subcommand environment also raises a FAILURE 
condition. 


HALT 


raised if an external attempt is made to interrupt and end execution of the program. The condition is 
usually raised at the end of the clause that was processed when the external interruption occurred. 
When a Rexx program is running in a full-screen or command prompt session, the Ctrl+Break key 
combination raises the halt condition. However, if Ctrl+Break is pressed while a command or 
non-Rexx external function is processing, the command or function ends. 


Notes: 


1. Application programs that use the Rexx language processor might use the RXHALT exit or the 
RexxStart programming interface to halt the execution of a Rexx macro. (See the Open Object 
Rexx: Programming Guide for details about exits.) 


2. Only SIGNAL ON HALT or CALL ON HALT can trap error 4, described in Appendix C. Error 
Numbers and Messages. 


LOSTDIGITS 


raised if a number used in an arithmetic operation has more digits than the current setting of 
NUMERIC DIGITS. Leading zeros are not counted in this comparison. You can specify the 
LOSTDIGITS condition only for SIGNAL ON. 


NOMETHOD 


raised if an object receives a message for which it has no method defined, and the object does not 
have an UNKNOWN method. You can specify the NOMETHOD condition only for SIGNAL ON. 


NOSTRING 


raised when the language processor requires a string value from an object and the object does not 
directly provide a string value. See Required String Values for more information. You can specify 
the NOSTRING condition only for SIGNAL ON. 


NOTREADY 


raised if an error occurs during an input or output operation. See Errors during Input and Output. 
This condition is ignored if the NOTREADY condition trap is already in the delayed state. 


NOVALUE 
raised if an uninitialized variable is used as: 
- A term in an expression 


* The name following the VAR subkeyword of a PARSE instruction 
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* A variable reference in a parsing template, an EXPOSE instruction, a PROCEDURE instruction, 
or a DROP instruction 


* A method selection override specifier in a message term 


Note: SIGNAL ON NOVALUE can trap any uninitialized variables except tails in compound variables. 


/* The following does not raise NOVALUE. */ 
signal on novalue 

a.-0 

say a.z 

say "NOVALUE is not raised." 

exit 


novalue: 

say "NOVALUE is raised." 

You can specify this condition only for SIGNAL ON. 
SYNTAX 


raised if any language-processing error is detected while the program is running. This includes all 
kinds of processing errors: 


* True syntax errors 
* "Run-time" errors (such as attempting an arithmetic operation on nonnumeric terms) 
* Syntax errors propagated from higher call or method invocation levels 
* Untrapped HALT conditions 
* Untrapped NOMETHOD conditions 
You can specify this condition only for SIGNAL ON. 
Notes: 
1. SIGNAL ON SYNTAX cannot trap the errors 3 and 5. 


2. SIGNAL ON SYNTAX can trap the errors 6 and 30 only if they occur during the execution of 
an INTERPRET instruction. 


For information on these errors, refer to Error Numbers and Messages. 


USER 


raised if a condition specified on the USER option of CALL ON or SIGNAL ON occurs. USER 
conditions are raised by a RAISE instruction that specifies a USER option with the same 
usercondition name. The specified usercondition can be any symbol, including those specified as 
possible values for condition. 


Any ON or OFF reference to a condition trap replaces the previous state (ON, OFF, or DELAY, and any 
trapname) of that condition trap. Thus, a CALL ON HALT replaces any current SIGNAL ON HALT 
(and a SIGNAL ON HALT replaces any current CALL ON HALT), a CALL ON or SIGNAL ON with a 
new trap name replaces any previous trap name, and any OFF reference disables the trap for CALL or 
SIGNAL. 
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11.1. Action Taken when a Condition Is Not Trapped 


When a condition trap is currently disabled (OFF) and the specified condition occurs, the default action 
depends on the condition: 


* For HALT and NOMETHOD, a SYNTAX condition is raised with the appropriate Rexx error number. 


* For SYNTAX conditions, the clause in error is terminated, and a SYNTAX condition is propagated to 
each CALL instruction, INTERPRET instruction, message instruction, or clause with function or 
message invocations active at the time of the error, terminating each instruction if a SYNTAX trap is 
not active at the instruction level. If the SYNTAX condition is not trapped at any of the higher levels, 
processing stops, and a message (see Error Numbers and Messages) describing the nature of the event 
that occurred usually indicates the condition. 


* For all other conditions, the condition is ignored and its state remains OFF. 


11.2. Action Taken when a Condition Is Trapped 


When a condition trap is currently enabled (ON) and the specified condition occurs, a CALL trapname 
or SIGNAL trapname instruction is processed automatically. You can specify the trapname after the 
NAME subkeyword of the CALL ON or SIGNAL ON instruction. If you do not specify a trapname, the 
name of the condition itself (for example, ERROR or FAILURE) is used. 


For example, the instruction call on error enables the condition trap for the ERROR condition. If the 
condition occurred, then a call to the routine identified by the name ERROR is made. The instruction 
call on error name commanderror Would enable the trap and call the routine COMMANDERROR if 
the condition occurred, and the caller usually receives an indication of failure. 


The sequence of events, after a condition has been trapped, varies depending on whether a SIGNAL or 
CALL is processed: 


* Ifthe action taken is a SIGNAL, execution of the current instruction ceases immediately, the condition 
is disabled (set to OFF), and SIGNAL proceeds as usually (see SIGNAL). 


If any new occurrence of the condition is to be trapped, a new CALL ON or SIGNAL ON instruction 
for the condition is required to re-enable it when the label is reached. For example, if SIGNAL ON 
SYNTAX is enabled when a SYNTAX condition occurs, a usual syntax error termination occurs if the 
SIGNAL ON SYNTAX label name is not found. 


* If the action taken is a CALL, the CALL trapname proceeds in the usual way (see CALL) when the 
instruction completes. The call does not affect the special variable RESULT. If the routine should 
RETURN any data, that data is ignored. 


When the condition is raised, and before the CALL is made, the condition trap is put into a delayed 
state. This state persists until the RETURN from the CALL, or until an explicit CALL (or SIGNAL) 
ON (or OFF) is made for the condition. This delayed state prevents a premature condition trap at the 
start of the routine called to process a condition trap. When a condition trap is in the delayed state, it 
remains enabled, but if the condition is raised again, it is either ignored (for ERROR and FAILURE) 
or (for the other conditions) any action (including the updating of the condition information) is 
delayed until one of the following events occurs: 
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1. ACALL ON or SIGNAL ON for the delayed condition is processed. In this case, a CALL or 
SIGNAL takes place immediately after the new CALL ON or SIGNAL ON instruction has been 
processed. 


2. A CALL OFF or SIGNAL OFF for the delayed condition is processed. In this case, the condition 
trap is disabled and the default action for the condition occurs at the end of the CALL OFF or 
SIGNAL OFF instruction. 


3. A RETURN is made from the subroutine. In this case, the condition trap is no longer delayed and 
the subroutine is called again immediately. 


On RETURN from the CALL, the original flow of execution is resumed, that is, the flow is not 
affected by the CALL. 


Notes: 


1. In all cases, the condition is raised immediately upon detection. If SIGNAL ON traps the 
condition, the current instruction is ended, if necessary. Therefore, the instruction during which an 
event occurs can only be partly processed. For example, if SYNTAX is raised during the 
evaluation of the expression in an assignment, the assignment does not take place. Note that the 
CALL for traps for which CALL ON is enabled can only occur at clause boundaries. If these 
conditions arise in the middle of an INTERPRET instruction, execution of INTERPRET can be 
interrupted and resumed later. Similarly, other instructions, for example DO or SELECT, can be 
temporarily interrupted by a CALL at a clause boundary. 


N 


. The state (ON, OFF, or DELAY, and any trapname) of each condition trap is saved on entry to a 
subroutine and is then restored on RETURN. This means that CALL ON, CALL OFF, SIGNAL 
ON, and SIGNAL OFF can be used in a subroutine without affecting the conditions set up by the 
caller. See CALL for details of other information that is saved during a subroutine call. 


[99] 


. The state of condition traps is not affected when an external routine is called by a CALL, even if 
the external routine is a Rexx program. On entry to any Rexx program, all condition traps have an 
initial setting of OFF. 


4. While user input is processed during interactive tracing, all condition traps are temporarily set 
OFF. This prevents any unexpected transfer of control--for example, should the user accidentally 
use an uninitialized variable while SIGNAL ON NOVALUE is active. For the same reason, a 
syntax error during interactive tracing does not cause the exit from the program but is trapped 
specially and then ignored after a message is given. 


5. The system interface detects certain execution errors either before the execution of the program 
starts or after the program has ended. SIGNAL ON SYNTAX cannot trap these errors. 


Note that a label is a clause consisting of a single symbol followed by a colon. Any number of 
successive clauses can be labels; therefore, several labels are allowed before another type of clause. 


11.3. Condition Information 


When a condition is trapped and causes a SIGNAL or CALL, this becomes the current trapped condition, 
and certain condition information associated with it is recorded. You can inspect this information by 
using the CONDITION built-in function (see CONDITION). 


The condition information includes: 
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* The name of the current trapped condition 

* The name of the instruction processed as a result of the condition trap (CALL or SIGNAL) 
* The status of the trapped condition 

* A descriptive string (see Descriptive Strings) associated with that condition 

* Optional additional object information (see Additional Object Information) 


The current condition information is replaced when control is passed to a label as the result of a 
condition trap (CALL ON or SIGNAL ON). Condition information is saved and restored across 
subroutine or function calls, including one because of a CALL ON trap and across method invocations. 
Therefore, a routine called by CALL ON can access the appropriate condition information. Any previous 
condition information is still available after the routine returns. 


11.3.1. Descriptive Strings 


The descriptive string varies, depending on the condition trapped: 


ERROR 


The string that was processed and resulted in the error condition. 


FAILURE 


The string that was processed and resulted in the failure condition. 


HALT 


Any string associated with the halt request. This can be the null string if no string was provided. 


LOSTDIGITS 
The number with excessive digits that caused the LOSTDIGITS condition. 


NOMETHOD 


The name of the method that could not be found. 


NOSTRING 


The readable string representation of the object causing the NOSTRING condition. 


NOTREADY 


The name of the stream being manipulated when the error occurred and the NOTREADY condition 
was raised. If the stream was a default stream with no defined name, then the null string might be 
returned. 


NOVALUE 


The derived name of the variable whose attempted reference caused the NOVALUE condition. 


532 ooRexx Reference Version 4.0.0 


Chapter 11. Conditions and Condition Traps 


SYNTAX 


Any string the language processor associated with the error. This can be the null string if you did 
not provide a specific string. Note that the special variables RC and SIGL provide information on 
the nature and position of the processing error. You can enable the SYNTAX condition trap only by 
using SIGNAL ON. 

USER 


Any string specified by the DESCRIPTION option of the RAISE instruction that raised the 
condition. If a description string was not specified, a null string is used. 


11.3.2. Additional Object Information 


The language processor can provide additional information, depending on the condition trapped: 


NOMETHOD 
The object that raised the NOMETHOD condition. 


NOSTRING 
The object that caused the NOSTRING condition. 


NOTREADY 
The stream object that raised the NOTREADY condition. 


SYNTAX 
An array containing the objects substituted into the secondary error message (if any) for the syntax 
error. If the message did not contain substitution values, a zero element array is used. 

USER 


Any object specified by an ADDITIONAL or ARRAY option of the RAISE instruction that raised 
the condition. 


11.3.3. The Special Variable RC 


When an ERROR or FAILURE condition is trapped, the Rexx special variable RC is set to the command 
return code before control is transferred to the target label (whether by CALL or by SIGNAL). 


Similarly, when SIGNAL ON SYNTAX traps a SYNTAX condition, the special variable RC is set to the 
syntax error number before control is transferred to the target label. 


11.3.4. The Special Variable SIGL 


Following any transfer of control because of a CALL or SIGNAL, the program line number of the clause 
causing the transfer of control is stored in the special variable SIGL. If the transfer of control is because 
of a condition trap, the line number assigned to SIGL is that of the last clause processed (at the current 
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subroutine level) before the CALL or SIGNAL took place. The setting of SIGL is especially useful after 
a SIGNAL ON SYNTAX trap when the number of the line in error can be used, for example, to control a 
text editor. Typically, code following the SYNTAX label can PARSE SOURCE to find the source of the 
data and then call an editor to edit the source file, positioned at the line in error. Note that in this case you 
might have to run the program again before any changes made in the editor can take effect. 


Alternatively, SIGL can help determine the cause of an error (such as the occasional failure of a function 
call) as in the following example: 


signal on syntax 

ашаз1 /* This is to create a syntax error */ 
say "SYNTAX error not raised" 

exit 


/* Standard handler for SIGNAL ON SYNTAX ж/ 

syntax: 

say "Rexx error" rc "in line" sigl":" "ЕВВОВТЕХТ" (rc) 
say "SOURCELINE" (sigl) 

trace ?r; nop 


This code first displays the error code, line number, and error message. It then displays the line in error, 
and finally drops into debug mode to let you inspect the values of the variables used at the line in error. 


11.3.5. Condition Objects 


A condition object is a directory returned by the Object option of the CONDITION built-in function. 
This directory contains all information currently available on a trapped condition. The information varies 
with the trapped condition. The Nil object is returned for any entry not available to the condition. The 
following entries can be found in a condition object: 


ADDITIONAL 
The additional information object associated with the condition. This is the same object that the 
Additional option of the CONDITION built-in function returns. The ADDITIONAL information 
may be specified with the ADDITIONAL or ARRAY options of the RAISE instruction. 
DESCRIPTION 
The string describing the condition. The Description option of the CONDITION built-in function 
also returns this value. 
INSTRUCTION 


The keyword for the instruction executed when the condition was trapped, either CALL or SIGNAL. 
The Instruction option of the CONDITION built-in function also returns this value. 


CONDITION 


The name of the trapped condition. The Condition name option of the CONDITION built-in 
function also returns this value. 
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RESULT 
Any result specified on the RETURN or EXIT options of a RAISE instruction. 


RC 


The major Rexx error number for a SYNTAX condition. This is the same error number assigned to 
the special variable RC. 


CODE 


The detailed identification of the error that caused a SYNTAX condition. This number is a 
nonnegative number in the form nn.nnn. The integer portion is the Rexx major error number (the 
same value as the RC entry). The fractional portion is a subcode that gives a precise indication of 
the error that occurred. 


ERRORTEXT 


The primary error message for a SYNTAX condition. This is the same message available from the 
ERRORTEXT built-in function. 


MESSAGE 


The secondary error message for a SYNTAX condition. The message also contains the content of 
the ADDITIONAL information. 


PACKAGE 


The Package object associated with the program where a syntax condition was raised. 


POSITION 


The line number in source code at which a SYNTAX condition was raised. 


PROGRAM 


The name of the program where a SYNTAX condition was raised. 


TRACEBACK 


A single-index list of formatted traceback lines. 


PROPAGATED 


The value 0 (false) if the condition was raised at the same level as the condition trap or the value 1 
(true) if the condition was reraised with RAISE PROPAGATE. 


ooRexx Reference Version 4.0.0 535 


Chapter 11. Conditions and Condition Traps 


536 ooRexx Reference Version 4.0.0 


Chapter 12. Concurrency 


Conceptually, each Rexx object is like a small computer with its own processor to run its methods, its 
memory for object and method variables, and its communication links to other objects for sending and 
receiving messages. This is object-based concurrency. It lets more than one method run at the same time. 
Any number of objects can be active (running) at the same time, exchanging messages to communicate 
with, and synchronize, each other. 


12.1. Early Reply 


Early reply provides concurrent processing. A running method returns control, and possibly a result, to 
the point from which it was called; meanwhile it continues running. The following figure illustrates this 
concept. 


Figure 12-1. Early Reply 


Method A Method B Possible Output 





Hello 
Hello 
'Hello' . Goodbye 
Hello 
Goodbye 
Goodbye 





Reply earlyresult 
do 3 

say 'Goodbye' 
end 





Method A includes a call to Method B. Method B contains a REPLY instruction. This returns control and 
a result to method A, which continues processing with the line after the call to Method B. Meanwhile, 
Method B also continues running. 


The chains of execution represented by method A and method B are called activities. An activity is a 
thread of execution that can run methods concurrently with methods on other activities. 


An activity contains a stack of invocations that represent the Rexx programs running on the activity. An 
invocation can be a main program invocation, an internal function or subroutine call, an external function 
or subroutine call, an INTERPRET instruction, or a message invocation. An invocation is activated when 
an executable unit is invoked and removed (popped) when execution completes. In the Early Reply 
figure, the programs begins with a single activity. The activity contains a single invocation, method A. 
When method A invokes method B, a second invocation is added to the activity. 


When method B issues a REPLY, a new activity is created (activity 2). Method B's invocation is removed 
from activity 1, and pushed on to activity 2. Because activities can execute concurrently, both method A 
and method B continue processing. The following figures illustrate this concept. 
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Figure 12-2. Before REPLY 


MethodA 


v~B 
do 3 


say 'Hello' 
end 


Method B 


Reply earlyresult 
do 3 

say 'Goodbye' 
end 


Figure 12-3. After REPLY 


Activity 1 
Method A 
v~B 
do 3 


say 'Hello' 
end 








Activity 2 
Method B 


Reply earlyresult 
do 3 

say 'Goodbye' 
end 





Here is an example of using early reply to run methods concurrently. 


/* Example of early reply */ 


objecti = .example “new 
object2 = .example^new 


say objecti^repeat(10, "Object 1 running") 
say object2^repeat(10, "Object 2 running") 


say "Main ended." 
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::class example 
::method repeat 
use arg reps,msg 
reply "Repeating" msg"," reps "times." 
do reps 
say msg 
end 


12.2. Message Objects 


A message object (see The Message Class) is an intermediary between two objects that enables 
concurrent processing. All objects inherit the START method (see the Message Class) from the object 
class. To obtain a message object, an object sends a START message to the object to which the message 
object will convey a message. The message is an argument to the START message as in the following 
example: 


a-p^start ("REVERSE") 


This line of code creates a message object, A, and sends it a start message. The message object then sends 
the REVERSE message to object P. Object P receives the message, performs any needed processing, and 
returns a result to message object A. Meanwhile the object that obtained message object A continues its 
processing. When message object A returns, it does not interrupt the object that obtained it. It waits until 
this object requests the information. Here is an example of using a message object to run methods 
concurrently. 


/* Example of using a message object */ 


objecti 
object2 - .example^new 


.example^new 


a = objecti^start("REPEAT",10,"Object 1 running") 
b = object2^start("REPEAT",10,"0bject 2 running") 


say a^result 

say b^result 

say "Main ended." 
exit 


::class example 
::method repeat 
use arg reps,msg 
do reps 
say msg 
end 
return "Repeated" msg"," reps "times." 
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12.3. Default Concurrency 


The instance methods of a class use the EXPOSE instruction to define a set of object variables. This 
collection of variables belonging to an object is called its object variable pool. The methods a class 
defines and the variables these methods can access is called a scope. Rexx’s default concurrency exploits 
the idea of scope. The object variable pool is a set of object subpools, each representing the set of 
variables at each scope of the inheritance chain of the class from which the object was created. Only 
methods at the same scope can access object variables at any particular scope. This prevents any name 
conflicts between classes and subclasses, because the object variables for each class are in different 
scopes. 


If you do not change the defaults, only one method of a given scope can run on a single object at a time. 
Once a method is running on an object, the language processor blocks other methods on other activities 
from running in the same object at the same scope until the method that is running completes. Thus, if 
different activities send several messages within a single scope to an object the methods run sequentially. 


The next example shows how the default concurrency works. 


/* Example of default concurrency for methods of different scopes */ 
objecti = .subexample^new 


say objecti^repeat(8, "Object 1 running call 1") /* These calls run */ 
say objecti^repeater(8, "Object 1 running call 2") /* concurrently ж/ 
say "Main ended." 

exit 


::class example 
::method repeat 
use arg reps,msg 
reply "Repeating" msg"," reps "times." 
do reps 
say msg 
end 


::class subexample subclass example 
::method repeater 
use arg reps,msg 
reply "Repeating" msg"," reps "times." 
do reps 

say msg 
end 


The preceding example produces output such as the following: 


Repeating Object 1 running call 1, 8 times. 
Übject 1 running call 1 

Repeating Object 1 running call 2, 8 times. 
Übject 1 running call 1 

Übject 1 running call 2 

Main ended. 


Übject 1 running call 1 
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Object 1 running call 2 
Object 1 running call 1 
Object 1 running call 2 
Object 1 running call 1 
Object 1 running call 2 
Object 1 running call 1 
Object 1 running call 2 
Object 1 running call 1 
Object 1 running call 2 
Object 1 running call 1 
Object 1 running call 2 
Object 1 running call 2 


The following example shows that methods of the same scope do not run concurrently by default. 


/* Example of methods with the same scope not running concurrently*/ 
objecti = .example^new 


say objecti^repeat(10,"O0bject 1 running call 1") /* These calls  */ 
say objecti^repeat(10,"O0bject 1 running call 2") /* cannot run ж/ 
say "Main ended." /* concurrently. */ 
exit 


::class example 
::method repeat 
use arg reps,msg 
reply "Repeating" msg"," reps "times." 
do reps 
say msg 
end 


The REPEAT method includes a REPLY instruction, but the methods for the two REPEAT messages in 
the example cannot run concurrently. This is because REPEAT is called twice at the same scope and 
requires exclusive access to the object variable pool. The REPLY instruction causes the first REPEAT 
message to transfer its exclusive access to the object variable pool to a new activity and continue 
execution. The second REPLY message also requires exclusive access and waits until the first method 
completes. 


If the original activity has more than one method active (nested method calls) with exclusive variable 
access, the first REPLY instruction is unable to transfer its exclusive access to the new activity and must 
wait until the exclusive access is again available. This may allow another method on the same object to 
run while the first method waits for exclusive access. 


12.3.1. Sending Messages within an Activity 


Whenever a message is invoked on an object, the activity acquires exclusive access (a lock) for the 
object’s scope. Other activities that send messages to the same object that required the locked scope 
waits until the first activity releases the lock. 


Suppose object A is running method Y, which includes: 
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self^z 


Sequential processing does not allow method Z to begin until method Y has completed. However, 
method Y cannot complete until method Z runs. A similar situation occurs when a subclass's overriding 
method does some processing and passes a message to its superclasses’ overriding method. Both cases 
require a special provision: If an invocation running on an activity sends another message to the same 
object, this method is allowed to run because the activity has already acquired the lock for the scope. 
This allows nested, nonconcurrent method invocations on a single activity without causing a deadlock 
situation. The language processor regards these additional messages as subroutine calls. 


Here is an example showing the special treatment of single activity messages. The REPEATER and 
REPEAT methods have the same scope. REPEAT runs on the same object at the same time as the 
REPEATER method because a message to SELF runs the REPEAT method. The language processor 
treats this as a subroutine call rather than as concurrently running two methods. 


/* Example of sending message to SELF */ 


objecti - .example^new 


object2 - .example^new 


say objecti^repeater(10, "Object 1 running") 
say object2^repeater(10, "Object 2 running") 


say "Main ended." 
exit 


::class example 
::method repeater 
use arg reps,msg 
reply "Entered repeater." 
say self^repeat(reps,msg) 
::method repeat 
use arg reps,msg 
do reps 
say msg 
end 
return "Repeated" msg"," reps "times." 


The activity locking rules also allow indirect object recursion. The following figure illustrates indirect 
object recursion. 
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Figure 12-4. Indirect Object Recursion 


Method M 
» Method М 





Method M in object A sends object B a message to run method N. Method N sends a message to object 
A, asking it to run method O. Meanwhile, method M is still running in object A and waiting for a result 
from method N. A deadlock would result. Because the methods are all running on the same activity, no 
deadlock occurs. 


12.4. Using Additional Concurrency Mechanisms 


Rexx has additional concurrency mechanisms that can add full concurrency so that more than one 
method of a given scope can run in an object at a time: 


* The SETUNGUARDED method of the Method class and the UNGUARDED option of the METHOD 
directive provide unconditional concurrency 


* GUARD OFF and GUARD ON control a method's exclusive access to an object's scope 


12.4.1. SETUNGUARDED Method and UNGUARDED Option 


The SETUNGUARDED method of the Method class and the UNGUARDED option of the :: METHOD 
directive control locking of an object's scope when a method is invoked. Both let a method run even if 
another method is active on the same object. 


Use the SETUNGUARDED method or UNGUARDED option only for methods that do not need 
exclusive use of their object variable pool, that is, methods whose execution can interleave with another 
method's execution without affecting the object's integrity. Otherwise, concurrent methods can produce 
unexpected results. 


To use the SETUNGUARDED method for a method you have created with the NEW method of the 
Method class, you specify: 


methodname ~SETUNGUARDED 


(See SETUNGUARDED for details about SETUNGUARDED.) 


Alternately, you can define a method with the :: METHOD directive, specifying the UNGUARDED 
option: 
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::METHOD methodname UNGUARDED 


12.4.2. GUARD ON and GUARD OFF 


You might not be able to use the SETUNGUARDED method or UNGUARDED option in all cases. A 
method might need exclusive use of its object variables, then allow methods on other activities to run, 
and perhaps later need exclusive use again. You can use GUARD ON and GUARD OFF to alternate 
between exclusive use of an object’s scope and allowing other activities to use the scope. 


By default, a method must wait until a currently running method is finished before it begins. GUARD 
OFF lets another method (running on a different activity) that needs exclusive use of the same object 
variables become active on the same object. See GUARD for more information. 


12.4.3. Guarded Methods 


Concurrency requires the activities of concurrently running methods to be synchronized. Critical data 
must be safeguarded so diverse methods on other activities do not perform concurrent updates. Guarded 
methods satisfy both these needs. 


A guarded method combines the UNGUARDED option of the :: METHOD directive or the 
SETUNGUARDED method of the Method class with the GUARD instruction. 


The UNGUARDED option and the SETUNGUARDED method both provide unconditional concurrency. 
Including a GUARD instruction in a method makes concurrency conditional: 


GUARD ON WHEN expression 


If the expression on the GUARD instruction evaluates to 1 (true), the method continues to run. If the 
expression on the GUARD instruction evaluates to 0 (false), the method does not continue running. 
GUARD reevaluates the expression whenever the value of an exposed object variable changes. When the 
expression evaluates to 1, the method resumes running. You can use GUARD to block running any 
method when proceeding is not safe. (See GUARD for details about GUARD.) 


Note: It is important to ensure that you use an expression that can be fulfilled. If the condition 
expression cannot be met, GUARD ON WHEN puts the program in a continuous wait condition. This 
can occur in particular when several activities run concurrently. In this case, a second activity can 
make the condition expression invalid before GUARD ON WHEN can use it. 


To avoid this, ensure that the GUARD ON WHEN statement is executed before the condition is set to 
true. Keep in mind that the sequence of running activities is not determined by the calling sequence, so it 
is important to use a logic that is independent of the activity sequence. 


12.4.4. Additional Examples 


The following example uses REPLY in a method for a write-back cache. 
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/* Method Write_Back */ 
use arg data /* Save data to be written ж/ 
геріу 0 /* Tell the sender all was OK ж/ 
self~disk_write(data) /* Now write the data */ 


The REPLY instruction returns control to the point at which method Write_Back was called, returning 
the result 0. The caller of method Write_Back continues processing from this point; meanwhile, method 
Write_Back also continues processing. 


The following example uses a message object. It reads a line asynchronously into the variable nextline: 


mymsg = infile^start("READLINE") /* Gets message object to carry ж/ 


/* message to INFILE ж/ 
/* do other work ж/ 
nextline-mymsg^ result /* Gets result from message object */ 


This creates a message object that waits for the read to finish while the sender continues with other work. 
When the line is read, Ше mymsg message object obtains the result and holds it until the sender requests it. 


Semaphores and monitors (bounded buffers) synchronize concurrency processes. Giving readers and 
writers concurrent access is a typical concurrency problem. The following sections show how to use 
guarded methods to code semaphore and monitor mechanisms and to provide concurrency for readers 
and writers. 


12.4.4.1. Semaphores 


A semaphore is a mechanism that controls access to resources, for example, preventing simultaneous 
access. Synchronization often uses semaphores. Here is an example of a semaphore class: 


Figure 12-5. Example of a Rexx Semaphore Class 


/жжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжж / 


/* A Rexx Semaphore Class. ж/ 
/ж ж/ 
/* This file implements a semaphore class іп Rexx. Тһе class is defined to ж/ 
/* the Global Rexx Environment. Тһе following methods are defined for ж/ 
/* this class: ж/ 
/ж init - Initializes а new semaphore. Accepts the following positional ж/ 
/ж parameters: ж/ 
/ж паше! - global name for this semaphore ж/ 
/ж if named default to set name іп ж/ 
/ж the class semDirectory ж/ 
/ж noshare - do not define named semaphore ж/ 
/ж in class semDirectory ж/ 
/ж Initial state (0 or 1) ж/ 
/ж setInitialState - Allow for subclass to have some post-initialization, ж/ 
/ж and do setup based оп initial state of semaphore ж/ 
/* Waiting - Is the number of objects waiting оп this semaphore. ж/ 
/* | Shared - Is this semaphore shared (Global). ж/ 
/* | Named - Is this semaphore named. ж/ 
/* Name - Is the name of a named semaphore. ж/ 
/ж setSem - Sets the semaphore and returns previous state. ж/ 
/* теве%беш - Sets state to unSet. ж/ 
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/ж 
/ж 
/ж 
/ж 
/ж 
/ж 
/ж 
/ж 
/ж 
/ж 
/ж 
/ж 
/ж 
/ж 
/ж 
/ж 
/ж 
/ж 
/ж 
/ж 
/ж 
/ж 
/ж 
/ж 


oncurrency 
querySem - Returns current state of semaphore. ж/ 
ж/ 
SemaphoreMeta - Is the metaclass for the semaphore classes. This class is ж/ 
set up so that when a namedSemaphore is shared, it maintains these ж/ 
named/shared semaphores as part of its state. These semaphores аге ж/ 
maintained іп а directory, and an UNKNOWN method is installed on the ж/ 
class to forward unknown messages to the directory. In this way the ж/ 
class can function as а class and "like" a directory, во [] syntax can ж/ 
be used to retrieve a semaphore from the class. ж/ 
ж/ 
ж/ 
Тһе following are in the subclass EventSemaphore. ж/ 
ж/ 
Post - Posts this semaphore. ж/ 
Query - Queries the number of posts since the last reset. ж/ 
Reset - Resets the semaphore. ж/ 
Wait - Waits on this semaphore. ж/ 
ж/ 
ж/ 
Тһе following аге in the subclass MutexSemaphore ж/ 
ж/ 
requestMutex - Gets exclusive use of semaphore. ж/ 
releaseMutex - Releases to allow someone else to use semaphore. ж/ 
NOTE: Currently anyone сап issue а release (need not be the owner). ж/ 


/жжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжж / 


/* 
/ж 
/ж 


::class SemaphoreMeta subclass class 


=== Start of Semaphore class. 


::method init 


expose semDict 





/* Be sure to initialize parent ж/ 


.message^new(self, .array^of("INIT", super), "а", arg(1,"a"))~send 


semDict - .directory^new 


::method unknown 


expose semDict 
use arg msgName, args 


.message^new(semDict, msgName, "a", 


if var("RESULT") then 
return result 

else 
return 


/* Forward all unknown messages */ 
/* to the semaphore dictionary ж/ 


args) ~send 


::class Semaphore subclass object metaclass SemaphoreMeta 


::method init 


expose sem waits shared name 
use arg semname, shr, state 
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waits = 0 /* No one waiting */ 
name = "" /* Assume unnamed ж/ 
shared = 0 /* Assume not shared ж/ 
веп - 0 /* Default to not posted ж/ 
if state = 1 Then /* Should initial state be set? ж/ 
sem = 1 
/* Was a name specified? ж/ 
if VAR("SEMNAME") & semname \= "" Then Do 
name = semname /* Yes, so set the name ж/ 
if shr \= "NOSHARE" Then Do /* Do we want to share this sem? ж/ 
shared = 1 /* Yes, mark it shared ж/ 
/* Shared add to semDict ж/ 
self~class[name] = self 
End 
End 
self~setInitialState(sem) /* Initialize initial state ж/ 


::method setInitialState 

/* This method intended to be ж/ 
пор /* overridden by subclasses ж/ 
::method setSem 
expose sem 
oldState - sem 
sem - 1 /* Set new state to 1 ж/ 


return oldState 


::method resetSem 
expose sem 

sem = 0 

return 0 


::method querySem 
expose sem 
return sem 


::method shared 
expose shared 
return shared /* Return true 1 or false O ж/ 


::method named 
expose name 


/* Does semaphore have a name? ж/ 
if name = "" Then return 0 /* No, not named ж/ 
Else return 1 /* Yes, it is named ж/ 
::method name 
expose name 
return name /* Return name or "" ж/ 
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::method incWaits 
expose waits 
waits = waits + 1 /* One more object waiting */ 


::method decWaits 
expose Waits 
waits = waits - 1 /* One object less waiting */ 


::method Waiting 
expose Waits 
return waits /* Return number of objects waiting */ 





Start of EventSemaphore class. === ж/ 


::class EventSemaphore subclass Semaphore public 
::method setInitialState 

expose posted posts 

use arg posted 


if posted then posts - 1 
else posts - O 

::method post 
expose posts posted 


self^setSem /* Set semaphore state ж/ 
posted = 1 /* Mark as posted ж/ 
reply 

posts = posts + 1 /* Increase the number of posts ж/ 


::method wait 
expose posted 


self~incWaits /* Increment number waiting ж/ 
guard off 

guard on when posted /* Now wait until posted ж/ 
геріу /* Return to caller ж/ 
self~decWaits /* Cleanup, 1 less waiting */ 


::method reset 
expose posts posted 


posted = self~resetSem /* Reset semaphore ж/ 
геріу /ж Do an early reply ж/ 
posts = 0 /* Reset number of posts ж/ 


::method query 
expose posts 
/* Return number of times 
return posts /* Semaphore has been posted 





Start of MutexSemaphore class. 
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::class MutexSemaphore subclass Semaphore public 


::method setInitialState 
expose owned 
use arg owned 


::method requestMutex 
expose Owned 


Do forever /* Do until we get the semaphore ж/ 
owned = self^setSem 
if Owned = 0 /* Was semaphore already set? ж/ 
Then leave /* Wasn't owned; we now have it */ 
else Do 


self^incWaits 


guard off /* Turn off guard status to let */ 

/* others come in */ 

guard on when \Owned /* Wait until not owned and get ж/ 

/* guard */ 

self^decWaits /* One less waiting for MUTEX ж/ 
Епа 


/ж бо up and see if we сап get it ж/ 
End 


::method releaseMutex 
expose owned 
owned = self~resetSem /* Reset semaphore ж/ 


Note: There аге functions available that use system semaphores. See SysCreateEventSem, апа 
SysCreateMutexSem. 


12.4.4.2. Monitors (Bounded Buffer) 


A monitor object consists of a number of client methods, WAIT and SIGNAL methods for client 
methods to use, and one or more condition variables. Guarded methods provide the functionality of 
monitors. Do not confuse this with the Monitor class (see The Monitor Class). 


::method init 

/* Initialize the bounded buffer */ 
expose size in out n 

use arg size 

in=1 

out = 1 

n=0 
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::method append unguarded 

/* Add to the bounded buffer if not full */ 
expose n size b. in 

guard on when n < size 

use arg b.in 

in = in//size*1 

n = nti 


::method take 

/* Remove from the bounded buffer if not empty */ 
expose n b. out size 

guard on when n > 0 

reply b.out 

out = out//size*i 


n = n-1 


12.4.4.3. Readers and Writers 


The concurrency problem of the readers and writers requires that writers exclude writers and readers, 
whereas readers exclude only writers. The UNGUARDED option is required to allow several concurrent 
readers. 


::method init 

expose readers writers 
readers = 0 

writers = 0 


::method read unguarded 

/* Read if no one is writing */ 
expose writers readers 

guard on when writers = 0 
readers = readers + 1 

guard off 


/* Read the data ж/ 

say "Reading (writers:" writers", readers:" readers")." 
guard on 

readers = readers - 1 


::method write unguarded 

/* Write if no-one is writing or reading */ 
expose writers readers 

guard on when writers + readers = 0 

writers = writers + 1 


/* Write the data */ 


say "Writing (writers:" writers", readers:" readers")." 
writers = writers - 1 
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The security manager provides a special environment that is safe even if agent programs try to perform 
unexpected actions. The security manager is called if an agent program tries to: 


* Call an external function 

* Use a host command 

* Use the :: REQUIRES directive 

* Access the .LOCAL directory 

* Access the ENVIRONMENT directory 


* Usea stream name in the input and output built-in functions (CHARIN, CHAROUT, CHARS, 
LINEIN, LINEOUT, LINES, and STREAM) 


13.1. Calls to the Security Manager 


When the language processor reaches any of the defined security checkpoints, it sends a message to the 
security manager for the particular checkpoint. The message has a single argument, a directory of 
information that pertains to the checkpoint. If the security manager chooses to handle the action instead 
of the language processor, the security manager uses the checkpoint information directory to pass 
information back to the language processor. 


Security manager methods must return a value of either 0 or 1 to the language processor. A value of 0 
indicates that the program is authorized to perform the indicated action. In this case, processing 
continues as usual. A value of 1 indicates that the security manager performed the action itself. The 
security manager sets entries in the information directory to pass results for the action back to the 
language processor. The security manager can also use the RAISE instruction to raise a program error for 
a prohibited access. Error message 98.948 indicates authorization failures. 


The defined checkpoints, with their arguments and return values, are: 


CALL 


sent for all external function calls. The information directory contains the following entries: 


NAME 


The name of the invoked function. 


ARGUMENTS 
An array of the function arguments. 


When the CALL method returns 1, indicating that it handled the external call, the security 
manager places the function result in the information directory as the entry RESULT. 
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COMMAND 


sent for all host command instructions. The information directory contains the following entries: 


COMMAND 


The string that represents the host command. 


ADDRESS 
The name of the target ADDRESS environment for the command. 


When the COMMAND method returns 1, indicating that it handled the command, the security 
manager uses the following information directory entries to return the command results: 


RC 


The command return code. If the entry is not set, a return code of 0 is used. 


FAILURE 
If a FAILURE entry is added to the information directory, a Rexx FAILURE condition is 
raised. 

ERROR 


If an ERROR entry is added to the information directory, a Rexx ERROR condition is 
raised. The ERROR condition is raised only if the FAILURE entry is not set. 


REQUIRES 


sent whenever a :: REQUIRES directive in the file is processed. The information directory contains 
the following entry: 


NAME 
The name of the file specified on the :: REQUIRES directive. 
When the REQUIRES method returns 1, indicating that it handled the request, the entry NAME in 


the information directory is replaced with the name of the actual file to load for the request. The 
REQUIRES method can also provide a security manager to be used for the program loaded by the 
: REQUIRES directive by setting the information direction entry SECURITYMANAGER into the 
desired security manager object. 


LOCAL 


sent whenever Rexx is going to access an entry in the .LOCAL directory as part of the resolution of 
the environment symbol name. The information directory contains the following entry: 


NAME 
The name of the target directory entry. 


When the LOCAL method returns 1, indicating that it handled the request, the information directory 
entry RESULT contains the directory entry. When RESULT is not set and the method returns 1, this 
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is the same as a failure to find an entry in the .LOCAL directory. Rexx continues with the next step 
in the name resolution. 
ENVIRONMENT 


sent whenever Rexx is going to access an entry in the .ENVIRONMENT directory as part of the 
resolution of the environment symbol name. The information directory contains the following entry: 


NAME 
The name of the target directory entry. 


When the ENVIRONMENT method returns 1, indicating that it handled the request, the 
information directory entry RESULT contains the directory entry. When RESULT is not set and the 
method returns 1, this is the same as a failure to find an entry in the .ENVIRONMENT directory. 
Rexx continues with the next step in the name resolution. 


STREAM 


sent whenever one of the Rexx input and output built-in functions (CHARIN, CHAROUT, CHARS, 
LINEIN, LINEOUT, LINES, or STREAM) needs to resolve a stream name. The information 
directory contains the following entry: 


NAME 
The name of the target stream. 


When the STREAM method returns 1, the information directory STREAM must be set to an object 
to be used as the stream target. This should be a stream object or another object that supports the 
Stream class methods. 


METHOD 


sent whenever a secure program attempts to send a message for a protected method (see the 
: METHOD directive :: METHOD) to an object. The information directory contains the following 
entries: 


OBJECT 


The object the protected method is issued against. 


NAME 


The name of the protected method. 


ARGUMENTS 
An array containing the method arguments. 


When the METHOD method returns 1, indicating that it handled the external call, the function 
result can be placed in the information directory as the method RESULT. 
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13.1.1. Example 


The following agent program includes all the actions for which the security manager defines checkpoints 
(for example, by calling an external function). 


Figure 13-1. Agent Program 


/* Agent */ 

interpret "echo Hello There" 

"dir foo.bar" 

call rxfuncadd sysloadfuncs, rexxutil, sysloadfuncs 
say result 

say syssleep(1) 

say linein("c:\profile") 

say .array 

.object^setmethod("SETMETHOD") 

: :геди1гез agent2.cmd 


The following server implements Ше security manager with three levels of security. For each action Ше 
security manager must check (for example, by calling an external routine): 


1. The audit manager (Dumper class) writes a record of the event but then permits the action. 
2. The closed cell manager (noWay class) does not permit the action to take place and raises an error. 


3. The replacement execution environment (Replacer class, a subclass of the noWay class) replaces the 
prohibited action with a different action. 


Figure 13-2. Example of Server Implementing Security Manager 


/* Server implements security manager */ 

parse arg program 

method = .method~newfile (program) 

say "Calling program" program "with an audit manager:" 

pull 

method~setSecurityManager (.dumper~new(. output) ) 
.go^new^^run(method) 

say "Calling program" program "with a function replacement execution environment:" 
pull 

method^setSecurityManager(.replacer^new) 
.go^new^^run(method) 

say "Calling program" program "with a closed cell manager:" 
pull 

signal on syntax 

method^setSecurityManager(.noWay^new) 

.go^new^^run(method) 

exit 


syntax: 
say "Agent program terminated with an authorization failure" 


exit 


::class go subclass object 
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::method run -- this is a NON-PRIVATE method! 
use arg m 
self^run:super(m) -- a PRIVATE method is called here! 


::class dumper 
::method init 


expose stream /* target stream for output */ 
use arg stream /* hook up the output stream */ 
::method unknown /* generic unknown method ж/ 
ехрове в%геаш /* need the global stream ж/ 
use arg name, args /* get the message and arguments ж/ 
/* write out the audit event ж/ 
stream^lineout(time() date() "Called for event" name) 
stream~lineout ("Arguments are:") /* write out the arguments */ 
info = args[1] /* info directory is the first arg ж/ 
do name over info /* dump the info directory ж/ 
stream^lineout("Item" name":" info[name]) 
end 
return 0 /* allow this to proceed */ 


::class noWay 


::method unknown /* everything trapped by unknown */ 
/* and everything is an error ж/ 

raise syntax 98.948 array("You didn't say the magic word!") 
::class replacer subclass noWay /* inherit restrictive UNKNOWN method*/ 
::method command /* issuing commands ж/ 
use arg info /* access the directory ж/ 
info^rc = 1234 /* set the command return code ж/ 
info^failure = .true /* raise a FAILURE condition ж/ 
return 1 /* return "handled" return value ж/ 
::method call /* external function/routine call ж/ 
use arg info /* access the directory ж/ 
/* all results are the same ж/ 


info~setentry("RESULT","uh, uh, uh...you didn't say the magic word") 








return 1 /* return "handled" return value */ 
::method stream /* I/O function stream lookup */ 
use arg info /* access the directory ж/ 
/* replace with a different stream  */ 
info^stream = .stream~new("c:\sample.txt") 
return 1 
/* return "handled" return value */ 
::method local /* .LOCAL variable lookup ж/ 
/ж по value returned at all */ 
return 1 /* return "handled" return value */ 
::method environment /* .ENVIRONMENT variable lookup */ 
/* no value returned at all */ 
return 1 /* return "handled" return value */ 
::method method /* protected method invocation */ 
use arg info /* access the directory ж/ 
/* all results are the same */ 


info~setentry("RESULT","uh, uh, uh...you didn't say the magic word") 
return 1 /* return "handled" return value */ 
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::method requires /* REQUIRES directive */ 
use arg info /* access the directory ж/ 
/* switch to load a different file ж/ 

info^name = "c:\samples\agent.cmd" 
info^securitymanager = self /* load under this authority */ 
return 1 /* return "handled" return value ж/ 
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Rexx defines Stream class methods to handle input and output and maintains the I/O functions for input 
and output externals. Using a mixture of Rexx I/O methods and Rexx I/O functions can cause 
unpredictable results. For example, using the LINEOUT method and the LINEOUT function on the same 
persistent stream object can cause overlays. 


When a Rexx I/O function creates a stream object, the language processor maintains the stream object. 
When a Rexx I/O method creates a stream object, it is returned to the program to be maintained. Because 
of this, when Rexx I/O methods and Rexx I/O functions referring to the same stream are in the same 
program, there are two separate stream objects with different read and write pointers. The program needs 
to synchronize the read and write pointers of both stream objects, or overlays occur. 


To obtain a stream object (for example, MYFIL), you could use: 


MyStream = .stream^new("MYFIL") 


You can manipulate stream objects with character or line methods: 


nextchar = MyStream^charin() 
nextline = MyStream^linein() 


In addition to stream objects, the language processor defines an external data queue object for 
interprogram communication. This queue object understands line functions only. 


A stream object can have a variety of sources or destinations including files, serial interfaces, displays, or 
networks. It can be transient or dynamic, for example, data sent or received over a serial interface, or 
persistent in a static form, for example, a disk file. 


Housekeeping for stream objects (opening and closing files, for example) is not explicitly part of the 
language definition. However, Rexx provides methods, such as CHARIN and LINEIN, that are 
independent of the operating system and include housekeeping. The COMMAND method provides the 
stream_command argument for those situations that require more granular access to operating system 
interfaces. 


14.1. The Input and Output Model 


The model of input and output for Rexx consists of the following logically distinct parts: 


* One or more input stream objects 
* One or more output stream objects 
* One or more external data queue objects 


The Rexx methods, instructions, and built-in routines manipulate these elements as follows. 
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14.1.1. Input Streams 


Input to Rexx programs is in the form of a serial character stream generated by user interaction or has the 
characteristics of one generated this way. You can add characters to the end of some stream objects 
asynchronously; other stream objects might be static or synchronous. 


The methods and instructions you can use on input stream objects are: 


* CHARIN method--reads input stream objects as characters. 
* LINEIN method--reads input stream objects as lines. 


e PARSE PULL and PULL instructions--read the default input stream object (.INPUT),if the external 
data queue is empty. PULL is the same as PARSE UPPER PULL except that uppercase translation 
takes place for PULL. 


* PARSELINEIN instruction--reads lines from the default input stream object regardless of the state of 
the external data queue. Usually, you can use PULL or PARSE PULL to read the default input stream 
object. 


In a persistent stream object, the Rexx language processor maintains a current read position. For a 
persistent stream: 


* The CHARS method returns the number of characters currently available in an input stream object 
from the read position through the end of the stream (including any line-end characters). 


* The LINES method determines if any data remains between the current read position and the end of 
the input stream object. 


* Youcan move the read position to an arbitrary point in the stream object with: 
* The SEEK or POSITION method of the Stream class 
* The COMMAND method’s SEEK or POSITION argument 
. The start argument of the CHARIN method 
. The line argument of the LINEIN method 
When the stream object is opened, this position is the start of the stream. 


In a transient stream, no read position is available. For a transient stream: 


* The CHARS and LINES methods attempt to determine if data is present in the input stream object. 
These methods return the value 1 for a device if data is waiting to be read or a determination cannot be 
made. Otherwise, these methods return 0. 


* The SEEK and POSITION methods of the Stream class and the COMMAND method's SEEK and 
POSITION arguments are not applicable to transient streams. 


14.1.2. Output Streams 


Output stream methods provide for output from a Rexx program. Output stream methods are: 


* SAY instruction--writes to the default output stream object ( . OUTPUT). 
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* CHAROUT method--writes in character form to either the default or a specified output stream object. 
* LINEOUT method--writes in lines to either the default or a specified output stream object. 


LINEOUT and SAY write the new-line character at the end of each line. Depending on the operating 
system or hardware, other modifications or formatting can be applied; however, the output data remains a 
single logical line. 


The Rexx language processor maintains the current write position in a stream. It is separate from the 
current read position. Write positioning is usually at the end of the stream (for example, when the stream 
object is first opened), so that data can be appended to the end of the stream. For persistent stream 
objects, you can set the write position to the beginning of the stream to overwrite existing data by giving 
a value of 1 for the CHAROUT start argument or the LINEOUT line argument. You can also use the 
CHAROUT start argument, the LINEOUT /ine argument, the SEEK or POSITION method, or the 
COMMAND method's SEEK or POSITION stream command to direct sequential output to some arbitrary 
point in the stream. 


Note: Once data is in a transient output stream object (for example, a network or serial link), it is no 
longer accessible to Rexx. 


14.1.3. External Data Queue 


Rexx provides queuing services entirely separate from interprocess communications queues. 


The external data queue is a list of character strings that only line operations can access. It is external to 
Rexx programs in that other Rexx programs can have access to the queue. 


The external data queue forms a Rexx-defined channel of communication between programs. Data in the 
queue is arbitrary; no characters have any special meaning or effect. 


Apart from the explicit Rexx operations described here, no detectable change to the queue occurs while a 
Rexx program is running, except when control leaves the program and is manipulated by external means 
(such as when an external command or routine is called). 


There are two kinds of queues in Rexx. Both kinds are accessed and processed by name. 


14.1.3.1. Unnamed Queues 


One unnamed queue is automatically provided for each Rexx program in operation. Its name is always 
"ОСЕСЕ:", and the language processor creates it when Rexx is called and no queue is currently 
available. All processes that are children of the process that created the queue can access it as long as the 
process that created it is still running. However, other processes cannot share the same unnamed queue. 
The queue is deleted when the process that created it ends. 


14.1.3.2. Named Queues 


Your program creates (and deletes) named queues. You can name the queue yourself or leave the naming 
to the language processor. Your program must know the name of the queue to use a named queue. To 
obtain the name of the queue, use the RXQUEUE function: 
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previous, queue-rxqueue("set",newqueuename) 


This sets the new queue name and returns the name of the previous queue. 


The following Rexx instructions manipulate the queue: 


* PULL or PARSE PULL--reads a string from the head of the queue. If the queue is empty, these 


instructions take input from .INPUT. 
* PUSH--stacks a line on top of the queue (LIFO). 
* QUEUE--adds a string to the tail of the queue (FIFO). 


Rexx functions that manipulate QUEUE: as a device name are: 


* LINEIN("QUEUE:")--reads a string from the head of the queue. If the queue is empty the program 
waits for an entry to be placed on the queue. 


* LINEOUT("QUEUE:","string")--adds a string to the tail of the queue (FIFO). 


* QUEUED--returns the number of items remaining in the queue. 


Here is an example of using a queue: 


Figure 14-1. Sample Rexx Procedure Using a Queue 


/* */ 
/* push/pull WITHOUT multiprogramming support ж/ 
/ж ж/ 
push date() time() /* push date and time ж/ 
do 1000 /* let's pass some time ж/ 

пор /* doing nothing */ 
end /* end of loop ж/ 
pull ab /* pull them ж/ 
say "Pushed at " a b ", Pulled at " date() time() /* say now and then */ 
/* */ 
/* push/pull WITH multiprogramming support ж/ 
/ж (по error recovery, ог unsupported environment tests) ж/ 
/ж ж/ 
newq = RXQUEUE("Create") /* create a unique queue */ 
oq = RXQUEUE("Set" ,newq) /* establish new queue ж/ 
push date() time() /* push date and time ж/ 
do 1000 /* let's spend some time ж/ 

пор /* doing nothing */ 
end /* end of loop ж/ 
pull ab /* get pushed information ж/ 


say "Pushed at " a b ", Pulled at " date() time() /* 


call RXQUEUE "Delete",newq 
call RXQUEUE "Set",oq 


Special considerations: 


tell user 


*/ 


/* destroy unique queue created ж/ 
/* reset to default queue (not required) */ 


* External programs that must communicate with a Rexx procedure through defined data queues can use 
the Rexx-provided queue or the queue that QUEUE: references (if the external program runs in a child 
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process), or they can receive the data queue name through some interprocess communication 
technique, including argument passing, placement on a prearranged logical queue, or the use of usual 
interprocess communication mechanisms (for example, pipes, shared memory, or IPC queues). 


* Named queues are available across the entire system. Therefore, the names of queues must be unique 
within the system. If a queue named anyque exists, using the following function: 


newqueue - RXQUEUE("Create", "ANYQUE") 


results in an error. 


14.1.3.3. Multiprogramming Considerations 


The top-level Rexx program in a process tree owns an unnamed queue. However, any child process can 
modify the queue at any time. No specific process or user owns a named queue. The operations that 
affect the queue are atomic--the subsystem serializes the resource so that no data integrity problems can 
occur. However, you are responsible for the synchronization of requests so that two processes accessing 
the same queue get the data in the order it was placed on the queue. 


A specific process owns (creates) an unnamed queue. When that process ends, the language processor 
deletes the queue. Conversely, the named queues created with RxQueue("Create", queuename) exist 
until you explicitly delete them. The end of a program or procedure that created a named queue does not 
force the deletion of the private queue. When the process that created a queue ends, any data on the 
queue remains until the data is read or the queue is deleted. (The function call 

RxQueue("Delete", queuename) deletes a queue.) 


If a data queue is deleted by its creator, a procedure, or a program, the items in the queue are also deleted. 


14.1.4. Default Stream Names 


A stream name can be a file, a queue, a pipe, or any device that supports character-based input and 
output. If the stream is a file or device, the name can be any valid file specification. 


Windows and *nix define three default streams: 


e stdin (file descriptor 0) - standard input 
* stdout (file descriptor 1) - standard output 
* stderr (file descriptor 2) - standard error (output) 


Rexx provides .INPUT and .OUTPUT public objects. They default to the default input and output 
streams of the operating system. The appropriate default stream object is used when the call to a Rexx 
I/O function includes no stream name. The following Rexx statements write a line to the default output 
stream of the operating system: 


Lineout(,"Hello World") 
.Qutput~lineout ("Hello World") 


Rexx reserves the names STDIN, STDOUT, and STDERR to allow Rexx functions to refer to these stream 
objects. The checks for these names are not case-sensitive; for example, STDIN, stdin, and sTdIn all refer 
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to the standard input stream object. If you need to access a file with one of these names, qualify the name 
with a directory specification, for example, \stdin. 


Rexx also provides access to arbitrary file descriptors that are already open when Rexx is called. The 
stream name used to access the stream object is HANDLE: x. x is the number of the file descriptor you wish 
to use. You can use HANDLE: x as any other stream name; it can be the receiver of a Stream class method. 
If the value of x is not a valid file descriptor, the first I/O operation to that object fails. 


Notes: 


1. Once you close a HANDLE: x stream object, you cannot reopen it. 


2. HANDLE: х is reserved. If you wish to access a file or device with this name, include a directory 
specification before the name. For example, \HANDLE: x accesses the file HANDLE:x in the current 
directory. 


3. Programs that use the INPUT and .OUTPUT public objects are independent of the operating 
environment. 


14.1.5. Line versus Character Positioning 


Rexx lets you move the read or write position of a persistent stream object to any location within the 
stream. You can specify this location in terms of characters or lines. 


Character positioning is based upon the view of a stream as a simple collection of bytes of data. No 
special meaning is given to any single character. Character positioning alone can move the stream 
pointer. For example: 


MyStream^charin(10,0) 


moves the stream pointer so that the tenth character in MyStream is the next character read. But this does 
not return any data. If MyStream is opened for reading or writing, any output that was previously written 
but is still buffered is eliminated. Moving the write position always causes any buffered output to be 
written. 


Line positioning views a stream as a collection of lines of data. There are two ways of positioning by 
lines. If you open a stream in binary mode and specify a record length of x on the open, a line break 
Occurs every x characters. Line positioning in this case is an extension of character positioning. For 
example, if you open a stream in binary mode with record length 80, then the following two lines are 
exactly equivalent. 


MyStream^command(position 5 read line) 
MyStream^command(position 321 read char) 


Remember that streams and other Rexx objects are indexed starting with one rather than zero. 


The second way of positioning by lines is for non-binary streams. New-line characters separate lines in 
non-binary streams. Because the line separator is contained within the stream, ensure accurate line 
positioning. For example, it is possible to change the line number of the current read position by writing 
extra new-line characters ahead of the read position or by overwriting existing new-line characters. Thus, 
line positioning in a non-binary stream object has the following characteristics: 
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* To do line positioning, it is necessary to read the stream in circumstances such as switching from 
character methods to line methods or positioning from the end of the stream. 


* Ifyou rewrite a stream at a point prior to the read position, the line number of the current read position 
could become inaccurate. 


Note that for both character and line positioning, the index starts with one rather than zero. Thus, 
character position 1 and line position 1 are equivalent, and both point to the top of the persistent stream 
object. The Rexx I/O processing uses certain optimizations for positioning. These require that no other 
process is writing to the stream concurrently and no other program uses or manipulates the same 
low-level drive, directory specification, and file name that the language processor uses to open the file. If 
you need to work with a stream in these circumstances, use the system I/O functions. 


14.2. Implementation 


Usually, the dialog between a Rexx program and you as the user takes place on a line-by-line basis and 
is, therefore, carried out with the SAY, PULL, or PARSE PULL instructions. This technique considerably 
enhances the usability of many programs, because they can be converted to programmable dialogs by 
using the external data queue to provide the input you generally type. Use the PARSE LINEIN 
instruction only when it is necessary to bypass the external data queue. 


When a dialog is not on a line-by-line basis, use the serial interfaces the CHARIN and CHAROUT 
methods provide. These methods are important for input and output in transient stream objects, such as 
keyboards, printers, or network environments. 


Opening and closing of persistent stream objects, such as files, is largely automatic. Generally the first 
CHARIN, CHAROUT, CHARS, LINEIN, LINEOUT, or LINES message sent to a stream object opens 
that stream object. It remains open until you explicitly close it with a CHAROUT or LINEOUT or until 
the program ends. Using the LINEOUT method with only the name of a stream object (and no output 
string or line) closes the named stream object. The Stream class also provides OPEN and CLOSE 
methods and the COMMAND method, which can explicitly open or close a stream object. 


If you open a stream with the CHARIN, CHAROUT, LINEIN, or LINEOUT methods, it is opened for 
both reading and writing, if possible. You can use the OPEN method or the COMMAND method to open 
a stream for read-only or write-only operations. 


14.3. Operating System Specifics 


The COMMAND method of the Stream class determines the state of an input or output stream object 
and carries out specific operations (see command). It allows Rexx programs to open and close selected 
stream objects for read-only, write-only, or read and write operations, to move the read and write position 
within a stream object, to control the locking and buffering characteristics, and to obtain information 
(such as the size and the date of the last update). 
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14.4. Examples of Input and Output 


In most circumstances, communication with a user running a Rexx program uses the default input and 
output stream objects. For a question and answer dialog, the recommended technique is to use the SAY 
and PULL instructions on the INPUT and .OUTPUT objects. (You can use PARSE PULL if 
case-sensitive input is needed.) 


It is generally necessary to write to, or read from, stream objects other than the default. For example, the 


following program copies the contents of one stream to another. 


/ж 
/ж 
/ж 
/ж 


FILECOPY.CMD ж/ 

This routine copies, as lines, the stream or */ 
file that the first argument names to the stream */ 
or file the second argument names. It is assumed */ 


/* that the name is not an object, as it could be  */ 
/* if it is passed from another Rexx program. ж/ 
parse агр inputname, outputname 
inputobject = .stream^new(inputname) 
outputobject = .stream^new(outputname) 
signal on notready 
do forever 
outputobject~ lineout (inputobject~linein) 
end 
exit 
notready: 
return 


As long as lines remain in the named input stream, a line is read and is then immediately written to the 
named output stream. This program is easy to change so that it filters the lines before writing them. 


The following example illustrates how character and line operations can be mixed in a communications 
program. It converts a character stream into lines. 


/* COLLECT.CMD */ 
/* This routine collects characters from the stream */ 
/* the first argument names until a line is */ 
/* complete, and then places the line on the ж/ 
/ж external data queue. ж/ 
/ж The second argument is а single character that ж/ 
/* identifies the end of a line. */ 
parse arg inputname, lineendchar 
inputobject = .stream^new(inputname) 
buffer="" /* zero-length character accumulator */ 
do forever 

nextchar-inputobject^charin 


if nextchar-lineendchar then leave 
buffer-buffer||nextchar /* add to buffer */ 
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end 
queue buffer /* place it on the external data queue */ 


Here each line is built up in a variable called BUFFER. When the line is complete (for example, when the 
user presses the Enter key) the loop ends and the language processor places the contents of BUFFER on the 
external data queue. The program then ends. 


14.5. Errors during Input and Output 


The Rexx language offers considerable flexibility in handling errors during input or output. This is 
provided in the form of a NOTREADY condition that the CALL ON and SIGNAL ON instructions can 
trap. The STATE and DESCRIPTION methods can elicit further information. 


When an error occurs during an input or output operation, the function or method called usually 
continues without interruption (the output method returns a nonzero count). Depending on the nature of 
the operation, a program has the option of raising the NOTREADY condition. The NOTREADY 
condition is similar to the ERROR and FAILURE conditions associated with commands in that it does 
not cause a terminating error if the condition is raised but is not trapped. After NOTREADY has been 
raised, the following possibilities exist: 


* Ifthe NOTREADY condition is not trapped, processing continues without interruption. The 
NOTREADY condition remains in the OFF state. 


* If SIGNAL ON NOTREADY traps the NOTREADY condition, the NOTREADY condition is raised. 
Processing of the current clause stops immediately, and the SIGNAL takes place as usual for condition 
traps. 


* If CALL ON NOTREADY traps the NOTREADY condition, the NOTREADY condition is raised, but 
execution of the current clause is not halted. The NOTREADY condition is put into the delayed state, 
and processing continues until the end of the current clause. While processing continues, input 
methods that refer to the same stream can return the null string and output methods can return an 
appropriate count, depending on the form and timing of the error. At the end of the current clause, the 
CALL takes place as usual for condition traps. 


* If the NOTREADY condition is in the DELAY state (CALL ON NOTREADY traps the NOTREADY 
condition, which has already been raised), processing continues, and the NOTREADY condition 
remains in the DELAY state. 


After the NOTREADY condition has been raised and is in DELAY state, the "0" option of the 
CONDITION function returns the stream object being processed when the stream error occurred. 


The STATE method of the Stream class returns the stream object state as ERROR, NOTREADY, or UNKNOWN. 
You can obtain additional information by using the DESCRIPTION method of the Stream class. 


Note: SAY .OUTPUT and PULL .INPUT never raise the NOTREADY condition. However, the STATE and 
DESCRIPTION methods can return NOTREADY. 
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CHARIN (see charIn) 
CHAROUT (see charOut) 
CHARS (see chars) 

CLOSE (see close) 
COMMAND (see command) 
DESCRIPTION (see description) 
FLUSH (see flush) 

LINEIN (see lineIn) 
LINEOUT (see lineOut) 
LINES (see lines) 
MAKEARRAY (see makeArray) 
OPEN (see open) 

PARSE LINEIN (see PARSE) 
PARSE PULL (see PARSE) 
POSITION (see position) 
PULL (see PULL) 

PUSH (see PUSH) 
QUALIFY (see qualify) 
QUERY (see query) 

QUEUE (see QUEUE) 
QUEUED (see QUEUED) 
SAY (see SAY) 

SEEK (see seek) 

STATE (see state) 
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14.6. Summary of Rexx I/O Instructions and Methods 


The following lists Rexx I/O instructions and methods: 
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In addition to the TRACE instruction described in TRACE, there are the following debugging aids. 


15.1. Interactive Debugging of Programs 


The debug facility permits interactively controlled execution of a program. Adding the prefix character ? 
to the TRACE instruction or the TRACE function (for example, TRACE ?І or TRACE(?1)) turns on 
interactive debugging and indicates to the user that interactive debugging is active. Further TRACE 
instructions in the program are ignored, and the language processor pauses after nearly all instructions 
that are traced at the console (see Debugging Aids for the exceptions). When the language processor 
pauses, the following debug actions are available: 


* Entering a null line causes the language processor to continue with the execution until the next pause 
for debugging input. Repeatedly entering a null line, therefore, steps from pause point to pause point. 
For TRACE ?А, for example, this is equivalent to single-stepping through the program. 


* Entering an equal sign (2) with no surrounding whitespace causes the language processor to reexecute 
the clause last traced. For example, if an IF clause is about to take the wrong branch, you can change 
the value of the variables on which it depends, and then reexecute it. 


Once the clause has been reexecuted, the language processor pauses again. 


* Anything else entered is treated as a line of one or more clauses, and processed immediately (that is, 
as though DO; line; END; had been inserted in the program). The same rules apply as for the 
INTERPRET instruction (for example, DO-END constructs must be complete). If an instruction 
contains a syntax error, a standard message is displayed and you are prompted for input again. 
Similarly, all other SIGNAL conditions are disabled while the string is processed to prevent 
unintentional transfer of control. 


During interpretation of the string, no tracing takes place, except that nonzero return codes from 
commands are displayed. The special variable RC and the environment symbol .RS are not set by 
commands executed from the string. Once the string has been processed, the language processor 
pauses again for further debugging input. 


Interactive debug is turned off in either of the following cases: 


* A TRACE instruction uses the ? prefix while interactive debug is in effect 


* At any time, if TRACE 0 or TRACE with no options is entered 


15.2. Debugging Aids 


The numeric form of the TRACE instruction can be used to allow sections of the program to be executed 
without pause for debugging input. TRACE n (that is, a positive result) allows execution to continue, 
skipping the next n pauses (when interactive debugging is or becomes active). TRACE -n (that is, a 
negative result) allows execution to continue without pause and with tracing inhibited for n clauses that 
would otherwise be traced. The trace action a TRACE instruction selects is saved and restored across 


ooRexx Reference Version 4.0.0 567 


Chapter 15. Debugging Aids 


subroutine calls. This means that if you are stepping through a program (for example, after using TRACE 
?R to trace results) and then enter a subroutine in which you have no interest, you can enter TRACE 0 to 
turn off tracing. No further instructions in the subroutine are traced, but on return to the caller, tracing is 
restored. 


Similarly, if you are interested only in a subroutine, you can put a TRACE ?R instruction at its start. 
Having traced the routine, the original status of tracing is restored and, if tracing was off on entry to the 
subroutine, tracing and interactive debugging are turned off until the next entry to the subroutine. 


Because any instructions can be executed in interactive debugging you have considerable control over 
the execution. 


The following are some examples: 


Say expr /* displays the result of evaluating the */ 
/* expression */ 
name-expr /* alters the value of a variable */ 
Trace 0 /* (or Trace with no options) turns off */ 
/* interactive debugging and all tracing ж/ 
Тгасе ?А /* turns off interactive debugging but ж/ 
/* continues tracing all clauses ж/ 
exit /* terminates execution of the program ж/ 


do i=1 to 10; say stem.i; end 
/* displays ten elements of the array stem. */ 


Exceptions: Some clauses cannot safely be reexecuted, and therefore the language processor does not 
pause after them, even if they are traced. These are: 


* Any repetitive DO clause, on the second or subsequent time around the loop. 

* AIL END clauses. 

* All THEN, ELSE, OTHERWISE, or null clauses. 

* All RETURN and EXIT clauses. 

* AIL SIGNAL clauses (but the language processor pauses after the target label is traced). 


* Any clause that causes a syntax error. They can be trapped by SIGNAL ON SYNTAX, but cannot be 
reexecuted. 


A pause occurs after a REPLY instruction, but the REPLY instruction cannot be reexecuted. 


15.3. RXTRACE Variable 


When the interpreter starts the interpretation of a Rexx procedure it checks the setting of the special 
environment variable, RXTRACE. If RXTRACE has been set to ON (not case-sensitive), the interpreter 
starts in interactive debug mode as if the Rexx instruction TRACE '?R' had been the first interpretable 
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instruction. All other settings of RXTRACE are ignored. RXTRACE is only checked when starting a new 
Rexx procedure. 


Use the SET command to set or query an environment variable or query all environment variables. To 
delete an environment variable, use SET variable=. 
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Keywords can be used as ordinary symbols in many unambiguous situations. The precise rules are given 
in this chapter. 


The free syntax of Rexx implies that some symbols are reserved for use by the language processor in 
certain contexts. 


Within particular instructions, some symbols can be reserved to separate the parts of the instruction. 
These symbols are referred to as keywords. Examples of Rexx keywords are the WHILE keyword in a 
DO instruction and the THEN keyword, which acts as a clause terminator in this case, following an IF or 
WHEN clause. 


Apart from these cases, only simple symbols that are the first token in a clause and that are not followed 


wow ШАШ 


by ап "=" ог ":" аге checked to see if they аге instruction keywords. The symbols can be freely used 
elsewhere in clauses without being understood as keywords. 


Be careful with host commands or subcommands with the same name as Rexx keywords. To avoid 
problems, enclose at least the command or subcommand in quotation marks. For example: 


"DELETE" Fn". "Ext 


You can then also use the SIGNAL ON NOVALUE condition to check the integrity of an executable. 


Alternatively, you can precede such command strings with two adjacent quotation marks to concatenate 
the null string to the beginning. For example: 


""Erase Fn"."Ext 
A third option is to enclose the entire expression, or the first symbol, in parentheses. For example: 


(Erase Fn"."Ext) 
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A special variable can be set automatically during processing of a Rexx program. There are five special 
variables: 


RC 


is set to the return code from any executed command (including those submitted with the 
ADDRESS instruction). After the trapping of ERROR or FAILURE conditions, it is also set to the 
command return code. When the SYNTAX condition is trapped, RC is set to the syntax error 
number (1-99). RC is unchanged when any other condition is trapped. 


Note: Commands executed manually during interactive tracing do not change the value of RC. 


RESULT 


is set by a RETURN instruction in a subroutine that has been called, or a method that was activated 
by a message instruction, if the RETURN instruction specifies an expression. (See EXIT, REPLY, 
and RETURN.) If the RETURN instruction has no expression, RESULT is dropped (becomes 
uninitialized). Note that an EXIT or REPLY instruction also sets RESULT. 


SELF 


is set when a method is activated. Its value is the object that forms the execution context for the 
method (that is, the receiver object of the activating message). You can use SELF to: 


* Runa method in an object in which a method is already running. For example, a Find Clues 
method is running in an object called Mystery Novel. When Find Clues finds a clue, it sends a 
Read Last Page message to Mystery Novel: 


Self^Read Last Page 


* Pass references about an object to the methods of other objects. For example, a Sing method is 
running in object Song. The code Singer2^Duet (self) would give the Duet method access to the 
same Song. 


SIGL 


is set to the line number of the last instruction that caused a transfer of control to a label (that is, any 
SIGNAL, CALL, internal function call, or trapped condition). See The Special Variable SIGL. 


SUPER 


is set when a method is activated. Its value is the class object that is the usual starting point for a 
superclass method lookup for the SELF object. This is the first immediate superclass of the class 
that defined the method currently running. (See Classes and Instances.) If the current method was 
defined by a class in the direct inheritance chain, SUPER will always refer to the immediate 
superclass that class. If the current method is defined by a mixin class, the SUPER variable will 
always be the superperclass of the mixin class. 
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The special variable SUPER lets you call a method in the superclass of an object. For example, the 
following Savings class has INIT methods that the Savings class, Account class, and Object class 
define. 


::class Account 


::method INIT 

expose balance 

use arg balance 

self^init:super /* Forwards to the Object INIT method ж/ 


::method TYPE 
return "an account" 


::method name attribute 
::class Savings subclass Account 


::method INIT 

expose interest rate 

use arg balance, interest rate 

self^init:super(balance) /* Forwards to the Account INIT method */ 


::method type 
return "a savings account" 


When the INIT method of the Savings class is called, the variable SUPER is set to the Account 
class object. The instruction: 

self~init:super(balance) /* Forwards to the Account INIT method */ 

calls the INIT method of the Account class rather than recursively calling the INIT method of the 


Savings class. When the INIT method of the Account class is called, the variable SUPER is 
assigned to the Object class. 


self~init:super /* Forwards to the Object INIT method ж/ 


calls the INIT method that the Object class defines. 


You can alter these variables like any other variable, but the language processor continues to set RC, 
RESULT, and SIGL automatically when appropriate. The EXPOSE, PROCEDURE, USE and DROP 
instructions also affect these variables. 


Rexx also supplies functions that indirectly affect the execution of a program. An example is the name 
that the program was called by and the source of the program (which are available using the PARSE 
SOURCE instruction). In addition, PARSE VERSION makes available the language version and date of 
Rexx implementation that is running. The built-in functions ADDRESS, DIGITS, FUZZ, FORM, and 
TRACE return other settings that affect the execution of a program. 
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The following section describes useful commands and services. 


18.1. Windows Commands 


COPY 


copies files. 
DELETE 


deletes files. 


DIR 


displays disk directories. 


ERASE 


erases files. 


MODE 


controls input and output device characteristics. 


PATH 


defines or displays the search path for commands and Rexx programs. See also Search Order. 


SET 


displays or changes Windows environment variables. See also VALUE. 


18.2. Linux Commands 


Most Commonly used commands are: 


cp 


copies files and directories. 
moves files and directories. 


removes files and directories. 
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ls 


displays files and directories. 


echo $path 


defines or displays the search path for commands and Rexx programs. See also Search Order. 


env 
displays or changes Linux environment variables. 


Any other Linux command can be used. For a description of these commands, see the respective Linux 
documentation (for example, man-pages). 


18.3. Subcommand Handler Services 


For a complete subcommand handler description, see the Open Object Rexx: Programming Guide. 


18.3.1. The RXSUBCOM Command 


The RXSUBCOM command registers, drops, and queries Rexx subcommand handlers. A Rexx 
procedure or script file can use RXSUBCOM to register dynamic-link library subcommand handlers. 
Once the subcommand handler is registered, a Rexx program can send commands to the subcommand 
handler with the Rexx ADDRESS instruction. For example, Rexx Dialog Manager programs use 
RXSUBCOM to register the ISPCIR subcommand handler. 


"RXSUBCOM REGISTER ISPCIR ISPCIR ISPCIR" 
Address ispcir 


See ADDRESS for details of the ADDRESS instruction. 


18.3.1.1. RXSUBCOM REGISTER 


RXSUBCOM REGISTER registers a dynamic-link library subcommand handler. This command makes 
a command environment available to Rexx. 


»-RXSUBCOM--REGISTER--envname--dllname--procname-------------- >< 
Parameters: 


envname 


The subcommand handler name. The Rexx ADDRESS instruction uses envname to send commands 
to the subcommand handler. 


dllname 


The name of the dynamic-link library file containing the subcommand handler routine. 
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procname 


The name of the dynamic-link library procedure within пате that Rexx calls as a subcommand 
handler. 


Return codes: 


0 
The command environment has been registered. 
10 
A duplicate registration has occurred. An envname subcommand handler in a different dynamic-link 
library has already been registered. Both the new subcommand handler and the existing 
subcommand handler can be used. 
30 
The registration has failed. Subcommand handler envname in library dllname is already registered. 
1002 
RXSUBCOM was unable to obtain the memory necessary to register the subcommand handler. 
-1 


А parameter is missing or incorrectly specified. 


18.3.1.2. RXSUBCOM DROP 
RXSUBCOM DROP deregisters a subcommand handler. 


>>-RXSUBCOM--DROP--envname--+--------- ho Se Se Ses >< 
+-а11паше-+ 


Parameters: 
envname 
The name of the subcommand handler. 


dliname 
The name of the dynamic-link file containing the subcommand handler routine. 


Return codes: 


The subcommand handler was successfully deregistered. 


30 


The subcommand handler does not exist. 
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40 
The environment was registered by a different process as RKSUBCOM_NONDROP. 


A parameter is missing or specified incorrectly. 


18.3.1.3. RXSUBCOM QUERY 
RXSUBCOM QUERY checks the existence of a subcommand handler. The query result is returned. 


>>-RXSUBCOM--QUERY--envname--+--------- несі асык але а ae >< 
+-а11пате-+ 


Parameters: 
envname 
The name of the subcommand handler. 


dliname 
The name of the dynamic-link file containing the subcommand handler routine. 


Return codes: 


The subcommand handler is registered. 


30 


The subcommand handler is not registered. 


A parameter is missing or specified incorrectly. 


18.3.1.4. RXSUBCOM LOAD 
RXSUBCOM LOAD loads a subcommand handler dynamic-link library. 


»»-RXSUBCOM--LOAD--envname---4--------- Movet o ee UL >< 
+-а11паше-+ 


Parameters: 


envname 


The name of the subcommand handler. 
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libname 
The name of the dynamic-link file containing the subcommand handler routine. 


Return codes: 


The dynamic-link library was located and loaded successfully. 
50 


The dynamic-link library was not located or could not be loaded. 


A parameter is missing or incorrectly specified. 


18.3.2. The RXQUEUE Filter 


>>-RXQUEUE--+----------- +--+-------- %-------------------------- >< 
*-queuename-* +-/ЕТЕ0--+ 
*-/LIF0--* 
*-/CLEAR-* 


The RXQUEUE filter usually operates on the default queue named SESSION. However, if an 
environment variable named RXQUEUE exists, the RXQUEUE value is used for the queue name. 


For a full description of Rexx queue services for applications programming, see External Data Queue. 


Parameters: 


queuename/LIFO 


stacks items from STDIN last in, first out (LIFO) on a Rexx queue. 


queuename/FIFO 


queues items from STDIN first in, first out (FIFO) on a Rexx queue. 


queuename/CLEAR 
removes all lines from a Rexx queue. 


RXQUEUE takes output lines from another program and places them on a Rexx queue. A Rexx 
procedure can use RXQUEUE to capture operating system command and program output for processing. 
RXQUEUE can direct output to any Rexx queue, either FIFO (first in, first out) or LIFO (last in, first 
out). 


RXQUEUE uses the environment variable RXQUEUE for the default queue name. When RKQUEUE 
does not have a value, RKQUEUE uses SESSION for the queue name. 


The following example obtains the Windows version number with RXQUEUE: 


/* Sample program to show simple use of RXQUEUE */ 
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/* Find out the Windows version number, using the ж/ 
/* VER command. VER produces two lines of */ 
/* output; one blank line, and one line with the*/ 


/* format "The Windows Version is n.nn" ж/ 
"VER |RXQUEUE" /* Put the data on the Queue */ 
pull . /* Get and discard the blank line */ 


Pull . "VERSION" number "]" /* The bracket is required for 
Windows 95, not for Windows NT */ 
Say "We are running on Windows Version" number 


Note that the syntax of the version string that is returned by Windows can vary, so the parsing syntax for 
retrieving the version number may be different. 


The following example processes output from the DIR command: 


/* Sample program to show how to use the RXQUEUE filter */ 
/* This program filters the output from a DIR command, ж/ 


/* ignoring small files. It displays a list of the */ 
/* large files, and the total of the sizes of the large */ 
/* files. */ 
Size limit - 10000 /* The dividing line */ 
/* between large and small*/ 

size total = 0 /* Sum of large file sizes*/ 
NUMERIC DIGITS 12 /* Set up to handle very ж/ 
/* large numbers */ 

/* Create a new queue so that this program cannot ж/ 


/* interfere with data placed on the queue by another ж/ 
/* program. */ 


queue_name = rxqueue("Create") 
Call rxqueue "Set", queue_name 


"DIR /N | RXQUEUE" queue_name 


/* DIR output starts with five header lines ж/ 
По 5 

Pull . /* discard header line ж/ 
Епа 

/* Now all the lines are file or directory lines, ж/ 
/* except for one at the end. ж/ 
Do queued() - 1 /* loop for lines we want */ 
Parse Pull . . size . name ./* get one name and size */ 

/* If the size field says "<DIR>", we ignore this ж/ 
/* line. ж/ 

If size <> "<DIR>" Then 

/* Now check size, and display ж/ 


If size > size_limit Then Do 
Say format(size,12) name 
size_total = size_total + size 
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End 
End 


Say "The total size of those files is" size_total 


/* Now we are done with the queue. We delete it, which */ 
/* discards the line remaining in it. */ 


Call rxqueue "DELETE", queue_name 


18.4. Distributing Programs without Source 


Open Object Rexx comes with a utility called RexxC. You can use this utility to produce versions of your 
programs that do not include the original program source. You can use these programs to replace any 
Rexx program file that includes the source, with the following restrictions: 


1. The SOURCELINE built-in function returns 0 for the number of lines in the program and raises an 
error for all attempts to retrieve a line. 


2. A sourceless program may not be traced. The TRACE instruction runs without error, but no tracing 
of instruction lines, expression results, or intermediate expression values occurs. 


The syntax of the RexxC utility is: 


>>-RexxC--inputfile--+------------ hese ааыа >< 
*-outputfile-* +-/s-+ 


If you specify the outputfile, the language processor processes the inputfile and writes the executable 
version of the program to the outputfile. If the outputfile already exists, it is replaced. 


If the language processor detects a syntax error while processing the program, it reports the error and 
stops processing without creating a new output file. If you omit the outputfile, the language processor 
performs a syntax check on the program without writing the executable version to a file. 


You can use the /s option to suppress the display of the information about the interpreter used. 


Note: You can use the in-storage capabilities of the RexxStart programming interface to process the 
file image of the output file. 


With version 2.1, the tokenized form has changed. All Open Object Rexx editions contain a utility called 
RxMigrate that can be used to change old tokenized forms to the new one. The recommended procedure 
is to create a new tokenized file from the original source with the new version of Open Object Rexx. 
However, if the source code is no longer available, RxMigrate can be used to convert the old tokenized 
file. The syntax of the RxMigrate utility is: 


»»-RxMigrate--inputfile--outputfile---------------------------- >< 
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This appendix provides you with additional information about the DO and LOOP keyword instructions. 


A.1. Simple DO Group 


If you specify neither repetitor nor conditional, the DO construct only groups a number of instructions 
together. They are processed once. For example: 


/* The two instructions between DO and END are both ж/ 


/* processed if A has the value "3". ж/ 
If a=3 then Do 

a=at2 

Say "Smile!" 

End 


A.2. Repetitive Loops 


If a DO or LOOP instruction has a repetitor phrase, a conditional phrase, or both, the group of 
instructions forms a repetitive loop. The instructions are processed according to the repetitor phrase, 
optionally modified by the conditional phrase. (See Conditional Phrases (WHILE and UNTIL).) 


A.2.1. Simple Repetitive Loops 


A simple repetitive loop is a repetitive loop in which the repetitor phrase is an expression that evaluates 
to a count of the iterations. 


If repetitor is omitted but there is a conditional or if the repetitor is FOREVER, the group of instructions 
is processed until the condition is satisfied or a Rexx instruction ends the loop (for example, LEAVE). 


In the simple form of a repetitive loop, exprr is evaluated immediately (and must result in a positive 
whole number or zero), and the loop is then processed that many times. 


Example: 


/* This displays "Hello" five times */ 


Loop 5 
say "Hello" 
end 


Note that, similar to the distinction between a command and an assignment, if the first token of exprr is a 
symbol and the second token is (or starts with) =, the controlled form of repetitor is expected. 
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A.2.2. Controlled Repetitive Loops 


The controlled form specifies controll, a control variable that is assigned an initial value (the result of 
expri, formatted as though 0 had been added) before the first execution of the instruction list. The 
variable is then stepped by adding the result of exprb before the second and subsequent times that the 
instruction list is processed. 


The instruction list is processed repeatedly as long as the end condition (determined by the result of 
exprt) is not met. If exprb is positive or 0, the loop is ended when controll is greater than exprt. If 
negative, the loop is ended when control] is less than exprt. 


The expri, exprt, and exprb options must result in numbers. They are evaluated only once, before the 
loop begins and before the control variable is set to its initial value. The default value for exprb is 1. If 
exprt is omitted, the loop runs infinitely unless some other condition stops it. 


Example: 
Loop I-3 to -2 by -1 /* Displays: */ 
say i /* 3 */ 
end /ж 2 ж/ 
/ж 1 ж/ 
/ж 0 ж/ 
/ж -1 */ 
/* -2 ж/ 


The numbers do not have to be whole numbers: 


Example: 
I-0.3 /* Displays: */ 
Do Y-I to I+4 by 0.7 /* 0.3 ж/ 
вау Ү /ж 1.0 ж/ 
end /* 1.7 */ 
/ж 2.4 ж/ 
/ж 3.1 ж/ 
/ж 3.8 ж/ 


The control variable сап be altered within the loop, and this can affect the iteration of the loop. Altering 
the value of the control variable is not considered good programming practice, though it can be 
appropriate in certain circumstances. 


Note that the end condition is tested at the start of each iteration (and after the control variable is stepped, 
on the second and subsequent iterations). Therefore, if the end condition is met immediately, the group 
of instructions can be skipped entirely. Note also that the control variable is referred to by name. If, for 
example, the compound name А.1 is used for the control variable, altering I within the loop causes a 
change in the control variable. 


The execution of a controlled loop can be limited further by a FOR phrase. In this case, you must specify 
exprf, and it must evaluate to a positive whole number or zero. This acts like the repetition count in a 
simple repetitive loop, and sets a limit to the number of iterations around the loop if no other condition 
stops it. Like the TO and BY expressions, it is evaluated only once--when the instruction is first 
processed and before the control variable receives its initial value. Like the TO condition, the FOR 
condition is checked at the start of each iteration. 


Example: 
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Loop Y=0.3 to 4.3 by 0.7 for 3 /* Displays: */ 
say Y /* 0.3 */ 
end /* 1.0 */ 
/* 1.7 */ 


In a controlled loop, the control] name describing the control variable can be specified on the END 
clause. This name must match controll in the DO or LOOP clause in all respects except the case (note 
that no substitution for compound variables is carried out). Otherwise, a syntax error results. This 
enables the nesting of loops to be checked automatically, with minimal overhead. 


Example: 


Loop K-1 to 10 


End к /ж Checks that this is the END for К loop */ 


Note: The NUMERIC settings can affect the successive values of the control variable because Rexx 
arithmetic rules apply to the computation of stepping the control variable. 


A.3. Repetitive Loops over Collections 


A collection loop specifies a control variable, control2, which receives a different value on each 
repetition of the loop. (For more information on control2, see DO.) These different values are taken from 
successive values of collection. The collection is any expression that evaluates to an object that provides 
a MAKEARRAY method, including stem variables. The collection returned determines the set of values 
and their order. Array, List, and Queue items return an array with the items in the appropriate order, as do 
Streams. Tables, Stems, Directories, etc. are not ordered so the items get placed in the array in no 
particular order. 


If the collection is a stem variable, the values are the tail names that have been explicitly assigned to the 
given stem. The order of the tail names is unspecified, and a program should not rely on any order. 


For other collection objects, the MAKEARRAY method of the specific collection class determines the 
values assigned to the control variable. 


All values for the loop iteration are obtained at the beginning of the loop. Therefore, changes to the target 
collection object do not affect the loop iteration. For example, using DROP to change the set of tails 
associated with a stem or using a new value as a tail does not change the number of loop iterations or the 
values over which the loop iterates. 


As with controlled repetition, you can specify the symbol that describes the control variable on the END 
clause. The control variable is referenced by name, and you can change it within the loop (although this 

would not usually be useful). You can also specify the control variable name on an ITERATE or LEAVE 
instruction. 


Example: 
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Astem.=0 
Astem.3="CCC" 
Astem.24-"XXX" 
loop k over Astem. 

say k Astem.k 
end k 


This example can produce: 


3 CCC 
24 XXX 


Or: 


24 XXX 
3 CCC 


See Concept of a Loop for a diagram. 


A.4. Conditional Phrases (WHILE and UNTIL) 


A conditional phrase can modify the iteration of a repetitive loop. It can cause the termination of a loop. 
It can follow any of the forms of repetitor (none, FOREVER, simple, or controlled). If you specify 
WHILE or UNTIL, exprw or expru, respectively, is evaluated after each loop using the latest values of all 
variables, and the loop is ended if exprw evaluates to 0 or expru evaluates to 1. 


For a WHILE loop, the condition is evaluated at the top of the group of instructions. For an UNTIL loop, 
the condition is evaluated at the bottom--before the control variable has been stepped. 


Example: 
Loop I-1 to 10 by 2 until 1>6 
say i 


end 
/ж Displays: 1! "3" "pu "7" */ 


Note: Using the LEAVE or ITERATE instructions can also modify the execution of repetitive loops. 


A.5. LABEL Phrase 


The LABEL phrase may be used to specify a name for the DO or LOOP. The can optionally be used for 


* a LEAVE instruction to identify the block to be left 
* an ITERATE instruction to identify the loop to be iterated 
* the END clause of the block, for additional checking. 
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Example: 


Loop label outer I=1 to 10 by 2 
if і > Б then do label inner 
if a = b then leave inner 


if c = b then iterate outer 
end inner 


say i 
end outer 
/* Displays: "1" изп "pu "7" */ 


In this example, the LEAVE instruction will exit the inner DO block. The ITERATE instruction will 
iterate the out LOOP instruction. 


If a LABEL phrase is used on a DO or LOOP, it overrides any name derived from any control variable 
name. That is, if label is used, the control variable cannot be used on a LEAVE, ITERATE, or END 
instruction to identify the block. Only the label name is valid. 
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A.6. Conceptual Model of Loops 


Figure A-1. Concept of a Loop 


Evaluate exprr+0 or expri+1 and then exprt+0, 


exprb+0, and exprf+0 in order written. 


Assign start value to control variable. 





Discontinue processing of 
Use TO value (exprt) ti test control variable for DO/LOOP group if TO value 


termination. is exceeded. 


Discontinue processing of 
Use count of iterations (exprr) to test for DO/LOOP group if number of 
termination. iterations is exceeded. 


«€ Discontinue processing of 
Use FOR value (exprf) to test for termination. DO/LOOP ehh if EON value 
(number of iterations through 
the loop is exceeded. 


Discontinue processing of 
Use WHILE expression (exprw) to test for DO/LOOP group if WHILE 
termination. condition is not met. 


Process instructions in the DO/LOOP group. 
Discontinue processing of 


Use UNTIL expression (expru) to test for DO/LOOP group if UNTIL 
termination. condition is met. 


Use BY value (exprb) to update control variable. 
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Figure A-2. Concept of Repetitive Loop over Collection 








Evaluate array= (collection)- makeArray 


Test index > array~items 


Index = index + 1 


Stop processing 
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This appendix lists some differences between Object Rexx and earlier versions of Rexx, and between 
Object Rexx for OS/2 and Open Object Rexx for Windows NT and *nix environments. 


B.1. Error Codes and Return Codes 


Some error codes have changed and some have been added. Also, for most errors you now receive two 
error messages. The first should be similar or identical to the message you would have seen previously. 
The second provides additional and more detailed information. So, for example, where you formerly 
received "Invalid Call to Routine", you now get further information on what is wrong with the call. 


Also, the return codes of host commands might be different. 


B.2. Error Detection and Reporting 


Some errors are now detected earlier. Formerly, Rexx would wait until it encountered an error during 
execution to report it to you. Now, some errors are reported before the first instruction in your Rexx 
script is executed. In particular, syntax errors are reported after you have invoked the program, but before 
it starts execution. 


B.3. Environment Variables 


Environment variables set within an Object Rexx program by the VALUE function or "SET" are not kept 
after the program termination. 


B.4. Stems versus Collections 


Stems are a general data structure that are powerful but abstract. In earlier releases of Rexx, you could 

use stems to create data structures of all types, such as arrays, stacks, and queues. These data structures 
were semantically neutral. Because stems were the basis for all of them, the code itself gave no hint of 
which structure was implemented and for what purpose. 


The best data structure job is not always the most powerful and abstract but the most specific and 
restrictive. Object Rexx provides a variety of data structures in the collection classes. This helps reduce 
errors because you can select the data structure that best meets your requirements. It also helps eliminate 
the misuse of data structures and adds a semantic context that makes programs easier to maintain. 
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B.5. Input and Output Using Functions and Methods 


Do not use a mixture of methods and functions for input and output because it can cause unpredictable 
results. For example, using the LINEOUT method and the LINEOUT function on the same persistent 
stream object can cause overlays. 


When a Rexx I/O function creates a stream object, the language processor stores the reference to the 
stream object in an internal table. When an I/O method creates a stream object, it is returned to the 
program to be maintained. Therefore, these two stream objects are separate stream objects with different 
read and write pointers. The program needs to synchronize the read and write pointers of both stream 
objects. Otherwise, overlays would occur. 


B.6. .Environment 


The .Environment directory is local and not system-global as in OS/2. This means that there is no 
difference between the scope of the .Local and .Environment directories. 


B.7. Deleting Environment Variables 


Value(envvar," "," ENVIRONMENT") does not delete an environment variable but sets the environment 
variable's value to "". Use Value(envvar,.nil," ENVIRONMENT") to delete an environment variable. 


B.8. Trace in Macrospace 


Functions in macrospace cannot be traced using the TRACE keyword. These functions are stored in an 
optimized format without source code. If you want to trace functions, do not load them into macrospace. 
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The error numbers produced by syntax errors during the processing of Rexx programs are all in the range 
1 to 99. Errors are raised in response to conditions, for example, SYNTAX, NOMETHOD, and 
PROPAGATE. When the condition is SYNTAX, the value of the error number is placed in the variable 
RC when SIGNAL ON SYNTAX is trapped. 


You can use the ERRORTEXT built-in function to return the text of an error message. 


Some errors have associated subcodes. A subcode is a one- to three-digit decimal extension to the error 
number, for example, 115 in 40.115. When an error subcode is available, additional information that 
further defines the source of the error is given. The ERRORTEXT built-in function cannot retrieve the 
secondary message, but it is available from the condition object created when SIGNAL ON SYNTAX 
traps an error. 


C.1. Error List 


C.1.1. Error 3 - Failure during initialization 


Explanation: 
The REXX program could not be read from the disk. 


The associated subcodes are: 


001 


Failure during initialization: File "filename" is unreadable 


900 


message 


901 


Failure during initialization: Program "program" was not found 


902 


Error writing output file "file" 


903 


Program "program_name" cannot be run by this version of the REXX interpreter 


904 


Failure during initialization: Program "program" needs to be tokenized. To run untokenized scripts 
you need a full version of Object REXX. 
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C.1.2. Error 4 - Program interrupted 


Explanation: 
The system interrupted the execution of your program because of an error or a user request. 


The associated subcodes are: 


001 


Program interrupted with condition condition 


900 


message 


C.1.3. Error 5 - System resources exhausted 


Explanation: 


While trying to execute a program, the language processor was unable to get the resources it needed to 
continue. For example, it could not get the space needed for its work areas or variables. The program that 
called the language processor might itself have already used up most of the available storage. Or a 
request for storage might have been for more than the implementation maximum. 


The associated subcodes are: 


900 


message 


C.1.4. Error 6 - Unmatched "/*" or quote 


Explanation: 


A comment or literal string was started but never finished. This could be because the language processor 
detected: 


* The end of the program (or the end of the string in an INTERPRET instruction) without finding the 
ending "*/" for a comment or the ending quotation mark for a literal string 


* The end of the line for a literal string. 


The associated subcodes are: 


001 


Unmatched comment delimiter ("/*") on line line number 


002 


Unmatched single quote (7) 
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003 


Unmatched double quote (") 


900 


message 


C.1.5. Error 7 - WHEN or OTHERWISE expected 


Explanation: 


At least one WHEN construct (and possibly an OTHERWISE clause) is expected within a SELECT 
instruction. This message is issued if any other instruction is found or there is no WHEN construct 
before the OTHERWISE or all WHEN expressions are false and an OTHERWISE is not present. A 
common cause of this error is if you forget the DO and END around the list of instructions following a 
WHEN. For example: 


WRONG RIGHT 

Select Select 

When a=c then When a=c then DO 
Say ’A equals C’ Say ’A equals C’ 
exit exit 

Otherwise nop end 

end Otherwise nop 
end 


The associated subcodes are: 


001 
SELECT on line Jine number requires WHEN 


002 
SELECT on line Ппе number requires WHEN, OTHERWISE, or END 


003 
All WHEN expressions of SELECT are false; OTHERWISE expected 


C.1.6. Error 8 - Unexpected THEN or ELSE 


Explanation: 


A THEN or an ELSE clause was found that does not match a corresponding IF or WHEN clause. This 
often occurs because of a missing END or DO...END in the THEN part of a complex IE... THEN...ELSE 
construction. For example: 


WRONG RIGHT 


If a=c then do; If a=c then do; 


ooRexx Reference Version 4.0.0 595 


Appendix C. Error Numbers and Messages 


Say EQUALS Say EQUALS 
exit exit 

else end 

Say NOT EQUALS else 


Say NOT EQUALS 


The associated subcodes are: 


001 
THEN has no corresponding IF or WHEN clause 


002 
ELSE has no corresponding THEN clause 


C.1.7. Error 9 - Unexpected WHEN or OTHERWISE 


Explanation: 


A WHEN or OTHERWISE was found outside of a SELECT construction. You might have accidentally 
enclosed the instruction in a DO...END construction by leaving out an END, or you might have tried to 
branch to it with a SIGNAL instruction (which does not work because the SELECT is then ended). 


The associated subcodes are: 


001 
WHEN has no corresponding SELECT 


002 
OTHERWISE has no corresponding SELECT 


C.1.8. Error 10 - Unexpected or unmatched END 


Explanation: 


More ENDs were found in your program than DO or SELECT instructions, or the ENDs did not match 
the DO or SELECT instructions. This message also occurs if you try to transfer control into the middle 
of a loop using SIGNAL. In this case, the language processor does not expect the END because it did not 
process the previous DO instruction. Remember also that SIGNAL deactivates any current loops, so it 
cannot transfer control from one place inside a loop to another. 


Another cause for this message is placing an END immediately after a THEN or ELSE subkeyword or 
specifying a name on the END keyword that does not match the name following DO. Putting the name of 
the control variable on ENDs that close repetitive loops can also help locate this kind of error. 


The associated subcodes are: 


001 
END has no corresponding DO or SELECT 
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002 


Symbol following END ("symbol") must match block specification name ("control_variable") on 
line line_number or be omitted 


003 


END corresponding to block on line symbol must not have a symbol following it because there is no 
LABEL or control variable; found "Jine number" 


004 


Symbol following END ("symbol") must match LABEL of SELECT specification 
("control variable") on line line number or be omitted 


005 
END must not immediately follow THEN 


006 
END must not immediately follow ELSE 


007 


END corresponding to SELECT on line symbol must not have a symbol following it because there 
is no LABEL; found "те number" 


C.1.9. Error 11 - Control stack full 


Explanation: 


Your program exceeds the nesting level limit for control structures (for example, DO...END and 
IF... THEN...ELSE). This could be because of a looping INTERPRET instruction, such as: 


line=’ INTERPRET line’ 
INTERPRET line 


These lines loop until they exceed the nesting level limit and the language processor issues this message. 
Similarly, a recursive subroutine or internal function that does not end correctly can loop until it causes 
this message. 


The associated subcodes are: 


001 


Insufficient control stack space; cannot continue execution 


900 


message 
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C.1.10. Error 13 - Invalid character in program 


Explanation: 


A character was found outside a literal (quoted) string that is not a whitespace character or one of the 
valid alphanumeric and special characters. 


The associated subcodes are: 


001 


Incorrect character in program "character" С hex_character’ X) 


900 


message 


C.1.11. Error 14 - Incomplete DO/SELECT/IF 


Explanation: 


At the end of the program or the string for an INTERPRET instruction, a DO or SELECT instruction was 
found without a matching END or an IF clause that is not followed by a THEN clause. Putting the name 
of the control variable on each END closing a controlled loop can help locate this kind of error. 


The associated subcodes are: 


001 


DO instruction on line line_number requires matching END 


002 


SELECT instruction on line /ine number requires matching END 


003 


THEN on line Ппе number must be followed by an instruction 


004 


ELSE on line пе number must be followed by an instruction 


901 
OTHERWISE on line /ine number requires matching END 


C.1.12. Error 15 - Invalid hexadecimal or binary string 


Explanation: 


Hexadecimal strings must not have leading or trailing whitespace characters and whitespace can only be 
embedded at byte boundaries. Only the digits 0-9 and the letters a-f and A-F are allowed. The following 
are valid hexadecimal strings: 


596 ooRexx Reference Version 4.0.0 


Appendix C. Error Numbers and Messages 


213? 
?^A3C2 1c34?x 
?1de8?x 


Binary strings can have whitespace only at the boundaries of groups of four binary digits. Only the digits 
0 and 1 are allowed. These are valid binary strings: 


2101195 
2110 110175 
2101101 11010011759 


You might have mistyped one of the digits, for example, typing a letter O instead of the number 0. Or 
you might have used the one-character symbol X or B (the name of the variable X or B, respectively) 
after a literal string when the string is not intended as a hexadecimal or binary specification. In this case, 
use the explicit concatenation operator (ll) to concatenate the string to the value of the symbol. 


The associated subcodes are: 


001 


Incorrect location of whitespace character in position position in hexadecimal string 


002 


Incorrect location of whitespace character in position position in binary string 


003 


1 


Only 0-9, a-f, A-F, and whitespace characters are valid in a hexadecimal string; found "character' 


004 


Only 0, 1, and whitespace characters are valid in a binary string; found "character" 


C.1.13. Error 16 - Label not found 


Explanation: 


A SIGNAL instruction has been executed or an event for which a trap was set with SIGNAL ON has 
occurred, and the language processor could not find the label specified. You might have mistyped the 
label or forgotten to include it. 


The associated subcodes are: 


001 


Label "Јаре! пате" not found 
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C.1.14. Error 17 - Unexpected PROCEDURE 


Explanation: 


A PROCEDURE instruction was encountered at an incorrect position. This could occur because no 
internal routines are active or because the PROCEDURE instruction was not the first instruction 
processed after the CALL instruction or function call. One cause for this error is dropping through to an 
internal routine, rather than calling it with a CALL instruction or a function call. 


The associated subcodes are: 


001 


PROCEDURE is valid only when it is the first instruction executed after an internal CALL or 
function invocation 


901 
INTERPRET data must not contain PROCEDURE 


C.1.15. Error 18 - THEN expected 


Explanation: 


A THEN clause must follow each REXX IF or WHEN clause. The language processor found another 
clause before it found a THEN clause. 


The associated subcodes are: 


001 


IF instruction on line /ine number requires matching THEN clause 


002 


WHEN instruction on line Ппе number requires matching THEN clause 


C.1.16. Error 19 - String or symbol expected 


Explanation: 


A symbol or string was expected after the CALL or SIGNAL keywords but none was found. You might 
have omitted the string or symbol or inserted a special character (such as a parenthesis). 


The associated subcodes are: 


001 
String or symbol expected after ADDRESS keyword 


002 
String or symbol expected after CALL keyword 
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006 


007 


900 


901 


902 


903 


904 


905 


906 


907 


908 


909 


911 
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String or symbol expected after NAME keyword 


String or symbol expected after SIGNAL keyword 


String or symbol expected after TRACE keyword 


String or symbol expected after PARSE keyword 


message 


String or symbol expected after :: CLASS keyword 


String or symbol expected after :: METHOD keyword 


String or symbol expected after :: ROUTINE keyword 


String or symbol expected after :: REQUIRES keyword 


String or symbol expected after EXTERNAL keyword 


String or symbol expected after METACLASS keyword 


String or symbol expected after SUBCLASS keyword 


String or symbol expected after INHERIT keyword 


String or symbol expected after tilde (~) 


String or symbol expected after superclass colon (:) 
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912 
String or symbol expected after STREAM keyword 


913 
String or symbol expected after MIXINCLASS keyword 


914 
String or symbol expected as :: ATTRIBUTE directive name 


915 
String or symbol expected as :: CONSTANT directive name 


916 
String or symbol expected as :: CONSTANT value 


917 
String or symbol expected as DIGITS value 


918 


String or symbol expected as FUZZ value 


919 
String or symbol expected as TRACE value 


C.1.17. Error 20 - Symbol expected 


Explanation: 


A symbol is expected after CALL ON, CALL OFF, END, ITERATE, LEAVE, NUMERIC, PARSE, 
SIGNAL ON, or SIGNAL OFF. Also, a list of symbols or variable references is expected after DROP, 
EXPOSE, and PROCEDURE EXPOSE. Either there was no symbol when one was required or the 
language processor found another token. 


The associated subcodes are: 


900 


message 


901 
Symbol expected after DROP keyword 


902 
Symbol expected after EXPOSE keyword 


903 
Symbol expected after PARSE keyword 
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904 
Symbol expected after PARSE VAR 


905 
NUMERIC must be followed by one of the keywords DIGITS, FORM, or FUZZ; found "symbol" 


906 


Symbol expected after "(" of a variable reference 


907 
Symbol expected after LEAVE keyword 


908 
Symbol expected after ITERATE keyword 


909 
Symbol expected after END keyword 


911 
Symbol expected after ON keyword 


912 
Symbol expected after OFF keyword 


913 
Symbol expected after USE ARG 


914 
Symbol expected after RAISE keyword 


915 
Symbol expected after USER keyword 


916 


Symbol expected after :: 


917 


Symbol expected after superclass colon (:) 


918 
Symbol expected after LABEL keyword 
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C.1.18. Error 21 - Invalid data on end of clause 


Explanation: 
A clause such as SELECT or NOP is followed by a token other than a comment. 


The associated subcodes are: 


900 


message 


901 


Data must not follow the NOP keyword; found "data" 


902 
Data must not follow the SELECT keyword; found "data" 


903 


Data must not follow the NAME keyword; found "data" 


904 


Data must not follow the condition name; found "data" 


905 


Data must not follow the SIGNAL label name; found "data" 


906 


Data must not follow the TRACE setting; found "data" 


907 


Data must not follow the LEAVE control variable name; found "data" 


908 


" 


Data must not follow the ITERATE control variable name; found "data 


909 


Data must not follow the END control variable name; found "data" 


911 
Data must not follow the NUMERIC FORM specification; found "data" 


912 
Data must not follow the GUARD OFF specification; found "data" 


913 
Data must not follow the :: CONSTANT value; found "data" 


604 ooRexx Reference Version 4.0.0 


Appendix C. Error Numbers and Messages 


C.1.19. Error 22 - Invalid character string 


Explanation: 


A literal string contains character codes that are not valid. This might be because some characters are not 
possible, or because the character set is extended and certain character combinations are not allowed. 


The associated subcodes are: 


001 


Incorrect character string "character. string" ( hex_string’ X) 


900 


message 


901 


Incorrect double-byte character 


C.1.20. Error 23 - Invalid data string 


Explanation: 


A data string (that is, the result of an expression) contains character codes that are not valid. This might 
be because some characters are not possible, or because the character set is extended and certain 
character combinations are not allowed. 


The associated subcodes are: 


001 


Incorrect data string "string" ( hex string" X) 


900 


message 


C.1.21. Error 24 - Invalid TRACE request 


Explanation: 


This message is issued when: 


* The option on a TRACE instruction or the argument to the built-in function does not start with A, C, 
Е F, I, L, N, О, or R. 


* In interactive debugging, you entered a number that is not a whole number. 


The associated subcodes are: 
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001 


901 


TRACE request letter must be one of "ACEFILNOR"; found "value" 


Numeric TRACE requests are valid only from interactive debugging 


C.1.22. Error 25 - Invalid subkeyword found 


Explanation: 


An unexpected token was found at his position of an instruction where a particular subkeyword was 
expected. For example, in a NUMERIC instruction, the second token must be DIGITS, FUZZ, or FORM. 


The associated subcodes are: 


001 


002 


003 


004 


011 


012 


015 


017 


CALL ON must be followed by one of the keywords ERROR, FAILURE, HALT, NOTREADY, 
USER, or ANY; found "word" 


CALL OFF must be followed by one of the keywords ERROR, FAILURE, HALT, NOTREADY, 
USER, or ANY; found "word" 


SIGNAL ON must be followed by one of the keywords ERROR, FAILURE, HALT, LOSTDIGITS, 
NOTREADY, NOMETHOD, NOSTRING, NOVALUE, SYNTAX, USER, or ANY; found "word" 


SIGNAL OFF must be followed by one of the keywords ERROR, FAILURE, HALT, LOSTDIGITS, 
NOTREADY, NOMETHOD, NOSTRING, NOVALUE, SYNTAX, USER, or ANY; found "word" 


NUMERIC FORM must be followed by one of the keywords SCIENTIFIC or ENGINEERING; 
found "word" 


PARSE must be followed by one of the keywords ARG, LINEIN, PULL, SOURCE, VALUE, VAR, 
or VERSION; found "word" 


NUMERIC must be followed by one of the keywords DIGITS, FORM, or FUZZ; found "word" 


PROCEDURE must be followed by the keyword EXPOSE or nothing; found "word" 
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902 
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906 


907 


908 


909 


911 


912 


913 


914 


915 
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message 


Unknown keyword on ::CLASS directive; found "word" 


Unknown keyword on :: METHOD directive; found "word" 


Unknown keyword on ::ROUTINE directive; found "word" 


Unknown keyword on ::REQUIRES directive; found "word" 


USE must be followed by the keyword ARG; found "word" 


RAISE must be followed by one of the keywords ERROR, FAILURE, HALT, LOSTDIGITS, 
NOMETHOD, NOSTRING, NOTREADY, NOVALUE, SYNTAX, or USER; found "word" 


Unknown keyword on RAISE instruction; found "word" 


Duplicate DESCRIPTION keyword found 


Duplicate ADDITIONAL or ARRAY keyword found 


Duplicate RETURN or EXIT keyword found 


GUARD ON or GUARD OFF must be followed by the keyword WHEN; found "word" 


GUARD must be followed by the keyword ON or OFF; found "word" 


CALL ON condition must be followed by the keyword NAME; found "word" 


SIGNAL ON condition must be followed by the keyword NAME; found "word" 
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916 
Unknown keyword on FORWARD instruction; found "keyword" 


917 
Duplicate TO keyword found 


918 
Duplicate ARGUMENTS or ARRAY keyword found 


919 
Duplicate RETURN or CONTINUE keyword found 


921 
Duplicate CLASS keyword found 


922 
Duplicate MESSAGE keyword found 


923 
SELECT must be followed by the keyword LABEL; found "word" 


924 
Unknown keyword on ::OPTIONS directive; found "word" 


C.1.23. Error 26 - Invalid whole number 


Explanation: 


An expression was found that did not evaluate to a whole number or is greater than the limit (the default 
is 999,999,999 for 32-bit system and 999,999,999,099,999.999 for 64-bit systems): 


* The positional patterns in parsing templates (including variable positional patterns) 
* The operand to the right of the power operator 

* The values of exprr and exprf in the DO instruction 

* The values given for DIGITS or FUZZ in the NUMERIC instruction 


* The number used in the option of the TRACE setting This error is also raised if the value is not 
permitted (for example, a negative repetition count in a DO instruction), or the division performed 
during an integer divide or remainder operation does not result in a whole number. 


The associated subcodes are: 
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002 


Value of repetition count expression in DO instruction must be zero or a positive whole number; 
found "value" 


003 


Value of FOR expression in DO instruction must be zero or a positive whole number; found "value" 


004 


Positional pattern of PARSE template must be a whole number; found "value" 


005 


DIGITS value must be a positive whole number; found "value" 


006 


FUZZ value must be zero or a positive whole number; found "value" 


007 


Number used in TRACE setting must be a whole number; found "value" 


008 


1 


Operand to Ше right of the power operator (**) must be а whole number; found "value' 


011 


Result of % operation did not result in a whole number 


012 


Result of // operation did not result in a whole number 


900 


message 


901 


Result of a method call did not result in a whole number; found "value" 


902 
Result of a COMPARETO method call did not result in a whole number; found "value" 


903 


Result of a COMPARE method call did not result in a whole number; found "value" 


C.1.24. Error 27 - Invalid DO syntax 


Explanation: 
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A syntax error was found in the DO instruction. You probably used BY, TO, FOR, WHILE, or UNTIL 
twice, used a WHILE and an UNTIL, or used BY, TO, or FOR when there is no control variable 
specified. 


The associated subcodes are: 


001 
WHILE and UNTIL keywords cannot be used on the same DO loop 


901 
Incorrect data following FOREVER keyword on the DO loop; found "data" 


902 
DO keyword keyword can be specified only once 


C.1.25. Error 28 - Invalid LEAVE or ITERATE 


Explanation: 


A LEAVE or ITERATE instruction was found at an incorrect position. Either no loop was active, or the 
name specified on the instruction did not match the control variable of any active loop. Note that internal 
routine calls and the INTERPRET instruction protect DO loops by making them inactive. Therefore, for 
example, a LEAVE instruction in a subroutine cannot affect a DO loop in the calling routine. You 
probably tried to use the SIGNAL instruction to transfer control within or into a loop. Because a 
SIGNAL instruction ends all active loops, any ITERATE or LEAVE instruction causes this message. 


The associated subcodes are: 


001 


LEAVE is valid only within a repetitive loop or labeled block instruction 


002 
ITERATE is valid only within a repetitive loop 


003 


Symbol following LEAVE ("symbol") must either match the label of a current loop or block 
instruction. 


004 


Symbol following ITERATE ("symbol") must either match the label of a current loop or be omitted 


005 


Symbol following ITERATE ("symbol") does not match a repetitive block instruction 
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C.1.26. Error 29 - Environment name too long 


Explanation: 


The environment name specified on the ADDRESS instruction is longer than permitted for the system 
under which the interpreter is running. 


The associated subcodes are: 


001 


Environment name exceeds limit characters; found "environment_name" 


C.1.27. Error 30 - Name or string too long 


Explanation: 


A variable name, label name, literal (quoted) string has exceeded the allowed limit of 250 characters. 
The limit for names includes any substitutions. A possible cause of this error is if you use a period (.) in a 
name, causing an unexpected substitution. Leaving off an ending quotation mark for a literal string, or 
putting a single quotation mark in a string, can cause this error because several clauses can be included in 
the string. For example, write the string 'don't' as 'don't' or "don't". 


The associated subcodes are: 


001 


Name exceeds 250 characters: "name" 


002 


Literal string exceeds 250 characters: "string" 


900 


message 


901 


Hexadecimal literal string exceeds 250 characters "string" 


902 


Binary literal string exceeds 250 characters "string" 


C.1.28. Error 31 - Name starts with number or ". 


Explanation: 


A variable was found whose name begins with a numeric digit or a period. You cannot assign a value to 
such a variable because you could then redefine numeric constants. 


The associated subcodes are: 


ooRexx Reference Version 4.0.0 611 


Appendix C. Error Numbers and Messages 


001 


A value cannot be assigned to a number; found "number" 


002 


Variable symbol must not start with a number; found "symbol" 


003 


Variable symbol must not start with a "."; found "symbol" 


900 


message 


C.1.29. Error 33 - Invalid expression result 


Explanation: 
The result of an expression was found not to be valid in the context in which it was used. 


The associated subcodes are: 


001 
Value of NUMERIC DIGITS ("value") must exceed value of NUMERIC FUZZ ("value") 


002 
Value of NUMERIC DIGITS ("value") must not exceed value 


900 


message 


901 
Incorrect expression result following VALUE keyword of ADDRESS instruction 


902 


Incorrect expression result following VALUE keyword of SIGNAL instruction 


903 


Incorrect expression result following VALUE keyword of TRACE instruction 


904 


Incorrect expression result following SYNTAX keyword of RAISE instruction 


C.1.30. Error 34 - Logical value not 0 or 1 


Explanation: 
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An expression was found in an IF, WHEN, DO WHILE, or DO UNTIL phrase that did not result in a 0 
or 1. Any value operated on by a logical operator must result in a 0 or 1. For example, the phrase If result 
then exit rc fails if result has a value other than O or 1. 


The associated subcodes are: 


001 


Value of expression following IF keyword must be exactly "0" or "1"; found "value" 


002 


Value of expression following WHEN keyword must be exactly "0" or "1"; found "value" 


003 


' 


Value of expression following WHILE keyword must be exactly "0" or "1"; found "value' 


004 


Value of expression following UNTIL keyword must be exactly "0" or "1"; found "value" 


005 


Value of expression to the left of the logical operator "operator" must be exactly "0" or "1"; found 
"value" 


006 


Value of logical list expression element must be exactly "0" or "1"; found "value" 


900 


message 


901 


Logical value must be exactly "0" or "1"; found "value" 


902 


' 


Value of expression following GUARD keyword must be exactly "0" or "1"; found "value' 


903 


Authorization return value must be exactly "0" or "1"; found "value" 


904 


Property logical value must be exactly "0", "1", "true", or "false"; found "value" 


C.1.31. Error 35 - Invalid expression 


Explanation: 


An expression contains a grammatical error. Possible causes: 
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* An expression is missing when one is required 


* You ended an expression with an operator 


* You specified, in an expression, two operators next to one another with nothing in between them 


* You did not specify a right parenthesis when one was required 


* You used special characters (such as operators) in an intended character expression without enclosing 
them in quotation marks 


The associated subcodes are: 


001 


900 


901 


902 


903 


904 


905 


906 


907 


908 


909 


Incorrect expression detected at "token" 


message 


Prefix operator "operator" is not followed by an expression term 


Missing conditional expression following IF keyword 


Missing conditional expression following WHEN keyword 


Missing initial expression for DO control variable 


Missing expression following BY keyword 


Missing expression following TO keyword 


Missing expression following FOR keyword 


Missing expression following WHILE keyword 


Missing expression following UNTIL keyword 
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911 
Missing expression following OVER keyword 


912 
Missing expression following INTERPRET keyword 


913 
Missing expression following OPTIONS keyword 


914 
Missing expression following VALUE keyword of an ADDRESS instruction 


915 
Missing expression following VALUE keyword of a SIGNAL instruction 


916 
Missing expression following VALUE keyword of a TRACE instruction 


917 
Missing expression following VALUE keyword of a NUMERIC FORM instruction 


918 


Missing expression following assignment instruction 


919 


Operator "operator" is not followed by an expression term 


921 
Missing expression following GUARD keyword 


922 
Missing expression following DESCRIPTION keyword of a RAISE instruction 


923 
Missing expression following ADDITIONAL keyword of a RAISE instruction 


924 
Missing "(" on expression list of the ARRAY keyword 


925 
Missing expression following TO keyword of a FORWARD instruction 


926 
Missing expression following ARGUMENTS keyword of a FORWARD instruction 
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927 
Missing expression following MESSAGE keyword of a FORWARD instruction 


928 
Missing expression following CLASS keyword of a FORWARD instruction 


929 
Missing expression in logical_expression_list 


930 
Missing expression following "=" token of a USE STRICT ARG instruction 


C.1.32. Error 36 - Unmatched "(" or "[" in expression 


Explanation: 


A matched parenthesis or bracket was found within an expression. There are more left parentheses than 
right parentheses or more left brackets than right brackets. To include a single parenthesis in a command, 
enclose it in quotation marks. 


The associated subcodes are: 


900 


message 


901 


Left parenthesis "(" in position position on line line number requires a corresponding right 
parenthesis ")" 


902 


Square bracket "[" in position position on line line_number requires a corresponding right square 
bracket "|" 


C.1.33. Error 37 - Unexpected ",", ")", or "J" 


Explanation: 


Either a comma was found outside a function invocation, or there are too many right parentheses or right 
square brackets in an expression. To include a comma in a character expression, enclose it in quotation 
marks. For example, write the instruction: 


Say Enter A, B, or C 


as follows: 


Say ’Enter A, B, or C? 
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The associated subcodes are: 


001 


Unexpected "," 


002 


Unmatched ")" in expression 


900 


message 


901 


Unexpected "]" 


C.1.34. Error 38 - Invalid template or pattern 


Explanation: 


A special character that is not allowed within a parsing template (for example, "%") has been found, or 
the syntax of a variable pattern is incorrect (that is, no symbol was found after a left parenthesis). This 
message is also issued if you omit the WITH subkeyword in a PARSE VALUE instruction. 


The associated subcodes are: 


001 


' 


Incorrect PARSE template detected at "column. position" 


002 


Incorrect PARSE position detected at "column position" 


003 
PARSE VALUE instruction requires WITH keyword 


900 


message 


901 
Missing PARSE relative position 


C.1.35. Error 39 - Evaluation stack overflow 


Explanation: 


The expression is too complex to be evaluated by the language processor. 
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C.1.36. Error 40 - Incorrect call to routine 


Explanation: 


An incorrect call to a routine was found. Possible causes: 


* You passed incorrect data (arguments) to the built-in or external routine. 
* You passed too many arguments to the built-in, external, or internal routine. 
* The external routine called was not compatible with the language processor. 


If you did not try to call a routine, you might have a symbol or a string adjacent to a "(" when you meant 
it to be separated by a blank or other operator. The language processor would treat this as a function call. 
For example, write TIME(4+5) as follows: TIME*(4+5) 


The associated subcodes are: 


001 


External routine "routine" failed 


003 


Not enough arguments in invocation of routine; minimum expected is number 


004 


Too many arguments in invocation of routine; maximum expected is number 


005 


Missing argument in invocation of routine; argument argument number is required 


011 


function name argument argument number must be a number; found "value" 


012 


function name argument argument number must be a whole number; found "value" 


013 


function name argument argument number must be zero or positive; found "value" 


014 


function name argument argument number must be positive; found "value" 


019 


function name argument 2, "value", is not in the format described by argument 3, "value" 


021 


function name argument argument number must not be a null string 
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022 


function name argument argument number must be a single character or null; found "value" 


023 


function name argument argument number must be a single character; found "value" 


024 


function name argument argument number must be a binary string; found "value" 


025 


function name argument argument number must be a hexadecimal string; found "value" 


026 


function name argument argument number must be a valid symbol; found "value" 


027 


function name argument 1 must be a valid stream name; found "value" 


029 


function name conversion to format "value" is not allowed 


032 


RANDOM difference between argument 1 ("value") and argument 2 ("value") must not exceed 
999,999,999 


033 


RANDOM argument 1 ("argument") must be less than or equal to argument 2 ("argument") 


034 


SOURCELINE argument 1 ("argument") must be less than or equal to the number of lines in the 
program (argument) 


035 


X2D argument 1 cannot be expressed as a whole number; found "value" 


043 


function name argument number must be a single non-alphanumeric character or the null string; 
found "value" 


044 


function name argument number, "value", is a format incompatible with the separator specified in 
argument number 


900 


message 
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901 


Result returned by routine is longer than length: "value" 


902 


function name argument argument number must not exceed the whole number limit. 


903 


function name argument argument number must be in the range 0-99; found "value" 


904 


function name argument argument number must be one of values; found "value" 


905 
TRACE setting letter must be one of " ACEFILNOR"; found "value" 


912 


' 


function name argument argument number must be a single-dimensional array; found "value' 


913 


function name argument argument number must have a string value; found "value" 


914 


Unknown VALUE function variable environment selector; found "value" 


915 


function name cannot be used with QUEUE: 


916 


Cannot read from a write-only property. 


917 


Cannot write to a read-only property or typelib element. 


918 


Invalid native function signature specification 


919 


Argument argument must have a stem object or stem name value; found "value" 


C.1.37. Error 41 - Bad arithmetic conversion 


Explanation: 


A term in an arithmetic expression is not a valid number or has an exponent outside the allowed range of 
whole number range. 
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You might have mistyped a variable name, or included an arithmetic operator in a character expression 
without putting it in quotation marks. 


The associated subcodes are: 


001 


Nonnumeric value ("value") used in arithmetic operation 


003 


Nonnumeric value ("value") used with prefix operator 


004 


Value of TO expression of DO instruction must be numeric; found "value" 


005 


Value of BY expression of DO instruction must be numeric; found "value" 


006 


Value of control variable expression of DO instruction must be numeric; found "value" 


007 


Exponent exceeds number digits; found "value" 


900 


message 


901 


Value of RAISE instruction SYNTAX expression must be numeric; found "value" 


C.1.38. Error 42 - Arithmetic overflow/underflow 


Explanation: 


The result of an arithmetic operation requires an exponent that is greater than the platform limit of nine 
digits for 32-bit systems or 18 for 64-bit systems. 


This error can occur during the evaluation of an expression (often as a result of trying to divide a number 
by 0) or while stepping a DO loop control variable. 


The associated subcodes are: 


001 


Arithmetic overflow detected at: "value operator value" 


002 


Arithmetic underflow detected at: "value operator value" 
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003 


Arithmetic overflow; divisor must not be zero 


900 


message 


901 


Arithmetic overflow; exponent ("exponent") exceeds number digits 


902 


Arithmetic underflow; exponent ("exponent") exceeds number digits 


903 


Arithmetic underflow; zero raised to a negative power 


C.1.39. Error 43 - Routine not found 


Explanation: 


A function has been invoked within an expression or a subroutine has been invoked by a CALL, but it 
cannot be found. Possible reasons: 


* The specified label is not in the program 

* Itis not the name of a built-in function 

* The language processor could not locate it externally 
Check if you mistyped the name. 


If you did not try to call a routine, you might have put a symbol or string adjacent to a "(" when you 
meant it to be separated by a blank or another operator. The language processor then treats it as a 
function call. For example, write the string 3(4+5) as 3*(4+5). 


The associated subcodes are: 


001 


Could not find routine "routine" 


900 


message 


901 
Could not find routine "routine" for ::REQUIRES 


622 ooRexx Reference Version 4.0.0 


Appendix C. Error Numbers and Messages 


C.1.40. Error 44 - Function or message did not return data 


Explanation: 


The language processor called an external routine within an expression. The routine seemed to end 
without error, but it did not return data for use in the expression. 


You might have specified the name of a program that is not intended for use as a REXX function. Call it 
as a command or subroutine instead. 


The associated subcodes are: 


001 


No data returned from function "function" 


900 


message 


C.1.41. Error 45 - No data specified on function RETURN 


Explanation: 
A REXX program has been called as a function, but returned without passing back any data. 


The associated subcodes are: 


001 


Data expected on RETURN instruction because routine "routine" was called as a function 


C.1.42. Error 46 - Invalid variable reference 


Explanation: 


Within an ARG, DROP, EXPOSE, PARSE, PULL, or PROCEDURE instruction, the syntax of a variable 
reference (a variable whose value is to be used, indicated by its name being enclosed in parentheses) is 
incorrect. The right parenthesis that must immediately follow the variable name might be missing or the 
variable name might be misspelled. 


The associated subcodes are: 


001 


Extra token ("token") found in variable reference list; ")" expected 


900 


message 


901 


Missing ")" in variable reference 
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902 


Extra token ("token") found in USE ARG variable reference; "," or end of instruction expected 


C.1.43. Error 47 - Unexpected label 


Explanation: 


A label was used in the expression being evaluated for an INTERPRET instruction or in an expression 
entered during interactive debugging. 


The associated subcodes are: 


001 
INTERPRET data must not contain labels; found "label" 


C.1.44. Error 48 - Failure in system service 


Explanation: 


The language processor stopped processing the program because a system service, such as stream input 
or output or the manipulation of the external data queue, has failed to work correctly. 


The associated subcodes are: 


001 


Failure in system service: service 


900 


message 


C.1.45. Error 49 - Interpretation error 


Explanation: 


A severe error was detected in the language processor or execution process during internal 
self-consistency checks. 


The associated subcodes are: 


001 


Interpretation error: unexpected failure initializing the interpreter 


900 


message 
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C.1.46. Error 88 - Invalid argument 


Explanation: 
An argument passed to a method, function, or routine was not valid. 


The associated subcodes are: 


900 


message 


901 


Missing argument; argument argument is required 


902 


Argument argument must be a number; found "value" 


903 


Argument argument must be a whole number; found "value" 


904 


Argument argument must be zero or a positive whole number; found "value" 


905 


Argument argument must be a positive whole number; found "value" 


906 


Argument argument must not exceed limit; found "value" 


907 


Argument argument must be in the range min to max; found "value" 


908 


Argument argument must not be a null string 


909 


Argument argument must have a string value 


910 


Argument argument is an incorrect pad or character argument; found "value" 


911 


Argument argument is an incorrect length argument; found "value" 


912 


Argument argument is an incorrect position argument; found "value" 


ooRexx Reference Version 4.0.0 625 


Appendix C. Error Numbers and Messages 


913 


Argument argument must have a single-dimensional array value 


914 


Argument argument must be of the class class 


915 


Argument argument could not be converted to type type 


916 


Argument argument must be one of values; found "value" 


917 


Argument argument reason 


918 


Argument argument is not in a valid format; found "value" 


919 


Argument argument is not in valid pointer format; found "value" 


920 


1 


Argument argument must have a stem object or stem name value; found "value' 


921 


Argument argument must be a valid double value; found "value" 


922 


Too many arguments in invocation; number expected 


C.1.47. Error 89 - Variable or message term expected 


Explanation: 


An instruction was expecting either a single Rexx variable symbol or a message term to be used for an 
assignment. 


The associated subcodes are: 


001 


The USE instruction requires a comma-separated list of variables or assignment message terms 


002 


The PARSE was expecting a variable or a message term. 
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C.1.48. Error 90 - External name not found 


Explanation: 


An external class, method, or routine (specified with the EXTERNAL option on a ::CLASS, 
:z METHOD, or ::ROUTINE directive, or as a second argument on a NEW message to the Method class) 
cannot be found. 


The associated subcodes are: 


900 


message 


997 


Unable to find external class "class" 


998 


Unable to find external method "method" 


999 


Unable to find external routine "routine" 


C.1.49. Error 91 - No result object 


Explanation: 
A message term requires a result object, but the method did not return one. 


The associated subcodes are: 
900 
message 


999 


Message "message" did not return a result 


C.1.50. Error 92 - OLE error 


The associated subcodes are: 


900 


message 


901 
An unknown OLE error occurred (HRESULT=hresult). 
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902 


903 


904 


905 


906 


907 


908 


909 


910 


911 


912 


Cannot convert OLE VARIANT to REXX object: The conversion of the VARIANT type 
varianttype into a REXX object failed. 


Cannot convert REXX object to OLE VARIANT: The conversion of rexx object into a VARIANT 
failed. 


The number of elements provided to the method or property is different from the number of 
parameters accepted by it. 


One of the parameters is not a valid VARIANT type. 


OLE exception: exc, name 


The requested method does not exist, or you tried to set the value of a read-only property. 


One of the parameters could not be coerced to the desired type. 


One or more of the parameters could not be coerced to the desired type. The first parameter with 
incorrect type is argument index. 


A required parameter was omitted. 


Could not create OLE instance. 


The object invoked has disconnected from its clients. 


C.1.51. Error 93 - Incorrect call to method 


Explanation: 


The specified method, built-in function, or external routine exists, but you used it incorrectly. 


The associated subcodes are: 
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900 


message 


901 


Not enough arguments in method; number expected 


902 


Too many arguments in invocation of method; number expected 


903 


Missing argument in method; argument argument is required 


904 


Method argument argument must be a number; found "value" 


905 


Method argument argument must be a whole number; found "value" 


906 


Method argument argument must be zero or a positive whole number; found "value" 


907 


1 


Method argument argument must be a positive whole number; found "value' 


908 


Method argument argument must not exceed limit; found "value" 


909 


Method argument argument must be in the range 0-99; found "value" 


911 


Method argument argument must not be null 


912 


Method argument argument must be a hexadecimal string; found "value" 


913 


Method argument argument must be a valid symbol; found "value" 


914 


Method argument argument must be one of arguments; found "value" 


915 


Method option must be one of "arguments"; found "value" 
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916 


Method argument argument must have a string value 


917 


Method method does not exist 


918 


Incorrect list index "index" 


919 


Incorrect array position "position" 


921 


Argument missing on binary operator 


922 


Incorrect pad or character argument specified; found "value" 


923 


Incorrect length argument specified; found "value" 


924 


Incorrect position argument specified; found "value" 


925 


Not enough subscripts for array; number expected 


926 


Too many subscripts for array; number expected 


927 


Length must be specified to convert a negative value 


928 


D2X value must be a valid whole number; found "value" 


929 


D2C value must be a valid whole number; found "value" 


931 


Incorrect location of whitespace character in position position in hexadecimal string 


932 


Incorrect location of whitespace character in position position in binary string 
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933 


Only 0-9, a-f, A-F, and whitespace characters are valid in a hexadecimal string; character found 
"character" 


934 


Only 0, 1, and whitespace characters are valid in a binary string; character found "character" 


935 
X2D result is not a valid whole number with NUMERIC DIGITS digits 


936 
C2D result is not a valid whole number with NUMERIC DIGITS digits 


937 


No more supplier items available 


938 


Method argument argument must have a string value 


939 


Method argument argument must have a single-dimensional array value 


941 


Exponent "exponent" is too large for number spaces 


942 


Integer part "integer" is too large for number spaces 


943 


method method target must be a number; found "value" 


944 


Method argument argument must be a message object 


945 


Missing argument in message array; argument argument is required 


946 


A message array must be a single-dimensional array with 2 elements 


947 
Method SECTION can be used only on single-dimensional arrays 


948 


Method argument argument must be of the class class 


ooRexx Reference Version 4.0.0 631 


Appendix C. Error Numbers and Messages 


949 


951 


952 


953 


954 


956 


957 


958 


959 


961 


962 


963 


964 


965 


966 


The index and value objects must be the same for PUT to an index-only collection 


Incorrect alarm time; found "time" 


Method argument argument is an array and does not contain all string values 


Method argument argument could not be converted to type type 


Method "method" can be used only on a single-dimensional array 


Element element of the array must be a string 


Element element of the array must be a subclass of the target object 


Positioning of transient streams is not valid 


An array cannot contain more than 99,999,999 elements 


Method argument argument must have a string value or an array value 


Invalid Base 64 encoded string. 


Call to unsupported or unimplemented method 


Application error: message 


Method name is ABSTRACT and cannot be directly invoked 


Incorrect queue index "index" 
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967 


NEW method is not supported for the name class 


968 


Invalid native method signature specification 


969 


Method argument argument must have a stem object value; found "value" 


970 
COPY method is not supported for object object 


C.1.52. Error 97 - Object method not found 


Explanation: 


The object does not have a method with the given name. A frequent cause of this error is an uninitialized 
variable. 


The associated subcodes are: 


001 


Object "object" does not understand message "message" 


900 


message 


C.1.53. Error 98 - Execution error 


Explanation: 


The language processor detected a specific error during execution. The associated error gives the reason 
for the error. 


The associated subcodes are: 


900 


message 


902 


Unable to convert object "object" to a double-float value 


903 


Unable to load library "name" 
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904 


905 


906 


907 


908 


909 


911 


913 


914 


915 


916 


917 


918 


919 


935 


Abnormal termination occurred 


Deadlock detected on a guarded method 


Incorrect object reference detected 


Object of type "type" was required 


Metaclass "metaclass" not found 


Class "class" not found 


Cyclic inheritance in program "program" 


Unable to convert object "object" to a single-dimensional array value 


Unable to convert object "object" to a string value 


A message object cannot be sent more than one SEND or START message 


Message object "object" received an error from message "message" 


Incorrect condition object received for RAISE OBJECT; found "value" 


No active condition available for PROPAGATE 


Unable to convert object "object" to a method 


REPLY can be issued only once per method invocation 
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936 
RETURN cannot return a value after a REPLY 


937 


EXIT cannot return a value after a REPLY 


938 


Message search overrides can be used only from methods of the target object 


939 


Additional information for SYNTAX errors must be a single-dimensional array of values 


941 
Unknown error number specified on RAISE SYNTAX; found "number" 


942 
Class "class" must be a MIXINCLASS for INHERIT 


943 


Class "class" is not a subclass of "class" base class "class" 


944 


Class "class" cannot inherit from itself, a superclass, or a subclass ("class") 


945 


Class "class" has not inherited class "class" 


946 


FORWARD arguments must be a single-dimensional array of values 


947 


FORWARD can only be issued in an object method invocation 


948 


Authorization failure: value 


951 


Concurrency not supported 


975 


Missing array element at position position 


976 


Stem object default value cannot be another stem object 
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978 


1 


Unable to load method "name" from library "library' 


979 


Unable to load routine "name" from library "library" 


980 


Unable to load native routine "name" 


981 


Target RexxContext is no longer active 


982 


Library "name" is not compatible with current interpreter version. 


983 


Execution thread does not match API thread context. 


C.1.54. Error 99 - Translation error 


Explanation: 
An error was detected in the language syntax. The associated error subcode identifies the syntax error. 


The associated subcodes are: 


900 


message 


901 


Duplicate ::CLASS directive instruction 


902 


Duplicate :: METHOD directive instruction 


903 


Duplicate :: ROUTINE directive instruction 


904 
Duplicate ::REQUIRES directive instruction 


905 
CLASS keyword on :: METHOD directive requires a matching ::CLASS directive 
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907 


EXPOSE must be the first instruction executed after a method invocation 


908 
INTERPRET data must not contain EXPOSE 


909 
GUARD must be the first instruction executed after EXPOSE or USE 


911 


GUARD can only be issued in an object method invocation 


912 
INTERPRET data must not contain GUARD 


913 


GUARD instruction did not include references to exposed variables 


914 


INTERPRET data must not contain directive instructions 


915 
INTERPRET data must not contain USE 


916 


Unrecognized directive instruction 


917 


Incorrect external directive name "method" 


918 


1 


USE ARG requires a "," between variable names; found "token' 


919 


REPLY can only be issued in an object method invocation 


921 


Incorrect program line in method source array 


922 


:z REQUIRES directives must appear before other directive instructions 


923 
INTERPRET data must not contain FORWARD 
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924 
INTERPRET data must not contain REPLY 


925 


An ATTRIBUTE method name must be a valid variable name; found "name" 


926 


Incorrect class external; too many parameters 


927 


"classname" is not a valid metaclass 


928 


Incorrect class external; class name missing or invalid 


929 


Incorrect class external; invalid class server "servername" 


930 


The "..." argument marker can only appear at the end of the argument list 


931 
Duplicate :: ATTRIBUTE directive instruction 


932 
Duplicate :: CONSTANT directive instruction 


C.2. RXSUBCOM Utility Program 


RXSUBCOM issues the following errors: 


C.2.1. Error 116 - The RXSUBCOM parameter REGISTER is 
incorrect. 


Explanation: 


RXSUBCOM REGISTER requires the following parameters: 


RXSUBCOM REGISTER Environment Name DII Name Procedure Name 


Environment Name 


is the name of the subcommand handler. 
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. DIL_Name 


is the name of the file containing the subcommand handler routine. 


. Procedure_Name 


is the name of the procedure that REXX calls as a subcommand handler. 


C.2.2. Error 117 - The RXSUBCOM parameter DROP is 
incorrect. 


Explanation: 


RXSUBCOM DROP requires that the subcommand handler name be specified. 


RXSUBCOM DROP Environment Name [011 Name] 


Environment Name 


is the name of the subcommand handler. 


„ОП Name 


is the name of the file containing the subcommand handler routine (optional). 


C.2.3. Error 118 - The RXSUBCOM parameter LOAD is 
incorrect. 


Explanation: 
RXSUBCOM LOAD requires that the subcommand handler name be specified. 


RXSUBCOM LOAD Environment Name [011 Name] 


Environment Name 


is the name of the subcommand handler. 


„ОП Name 


is the name of the file containing the subcommand handler routine (optional). 
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C.2.4. Error 125 - The RXSUBCOM parameter QUERY is 
incorrect. 


Explanation: 
RXSUBCOM QUERY requires the environment name be specified. 
RXSUBCOM QUERY Environment Name [011 Name] 


Environment Name 


is the name of the subcommand handler. 


„ОП Name 


is the name of the file containing the subcommand handler routine (optional). 


C.3. RXQUEUE Utility Program 


RXQUEUE issues the following errors: 


C.3.1. Error 119 - The REXX queuing system is not initialized. 


Explanation: 


The queuing system requires a housekeeping program to run. This program usually runs under the 
Presentation Manager shell. The program is not running. 


C.3.2. Error 120 - The size of the data is incorrect. 


Explanation: 


The data supplied to the RXQUEUE command is too long. The RXQUEUE program accepts data 
records containing 0 - 65472 bytes. A record exceeded the allowable limits. 


C.3.3. Error 121 - Storage for data queues is exhausted. 


Explanation: 


The queuing system is out of memory. No more storage is available to store queued data. 


C.3.4. Error 122 - The name %1 is not a valid queue name. 


Explanation: 
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The queue name contains an invalid character. Only the following characters can appear in queue names: 


C.3.5. Error 123 - The queue access mode is not correct. 


Explanation: 


An internal error occurred in RXQUEUE. The RXQUEUE program tried to access a queue with an 
incorrect access mode. Correct access modes are LIFO and FIFO. 


C.3.6. Error 124 - The queue %1 does not exist. 


Explanation: 


The command attempted to access a nonexistent queue. 


C.3.7. Error 131 - The syntax of the command is incorrect 


C.3.8. Error 132 - System error occurred while processing the 
command 


С.4. RexxC Utility Program 


When RexxC encounters a syntax error in a Rexx program while tokenizing or syntax checking it, 
RexxC returns the negated ooRexx error code. In addition, RexxC issues the following errors: 


C.4.1. Error 127 - The REXXC command parameters are 
incorrect. 


Explanation: 


The REXXC utility was invoked with zero or more than three parameters. REXXC accepts the following 
parameters: 


* То check the syntax of a REXX program: REXXC Program name [-s] 
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* To convert a REXX program into а sourceless executable file: REXXC Program пате 
Output file name [-s] 


* The -s option will suppress the copyright banner. 


C.4.2. Error 128 - Output file name must be different from 
input file name. 


C.4.3. Error 129 - SYNTAX: REXXC InProgramName 
[OutProgramName] [/S] 


C.4.4. Error 130 - Without OutProgramName REXXC only 
performs a syntax check 


C.4.5. Error 133 - SYNTAX: REXXC InProgramName 
[OutProgramName] [-s] 
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Any reference to a non-open source product, program, or service is not intended to state or imply that 
only non-open source product, program, or service may be used. Any functionally equivalent product, 
program, or service that does not infringe any Rexx Language Association (RexxLA) intellectual 
property right may be used instead. However, it is the user’s responsibility to evaluate and verify the 
operation of any non-open source product, program, or service. 


Any performance data contained herein was determined in a controlled environment. Therefore, the 
results obtained in other operating environments may vary significantly. Some measurements may have 
been made on development-level systems and there is no guarantee that these measurements will be the 
same on generally available systems. Furthermore, some measurement may have been estimated through 
extrapolation. Actual results may vary. Users of this document should verify the applicable data for their 
specific environment. 


Information concerning non-open source products was obtained from the suppliers of those products, 
their published announcements or other publicly available sources. RexxLA has not tested those products 
and cannot confirm the accuracy of performance, compatibility or any other claims related to 
non-RexxLA packages. Questions on the capabilities of non-RexxLA packages should be addressed to 
the suppliers of those products. 


All statements regarding RexxLA’s future direction or intent are subject to change or withdrawal without 
notice, and represent goals and objectives only. 


This information contains examples of data and reports used in daily business operations. To illustrate 
them as completely as possible, the examples include the names of individuals, companies, brands, and 
products. All of these names are fictitious and any similarity to the names and addresses used by an 
actual business enterprise is entirely coincidental. 


D.1. Trademarks 


Open Object Rexx™ and ooRexx™ are trademarks of the Rexx Language Association. 


The following terms are trademarks of the IBM Corporation in the United States, other countries, or both: 


1-2-3 

AIX 

IBM 
Lotus 
OS/2 
8/390 
VisualAge 


AMD is a trademark of Advance Micro Devices, Inc. 


Intel, Intel Inside (logos), MMX and Pentium are trademarks of Intel Corporation in the United States, 
other countries, or both. 


Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the Unites States, other 
countries, or both. 


Linux is a trademark of Linus Torvalds in the United States, other countries, or both. 


Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in 
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the United States, other countries, or both. 
UNIX is a registered trademark of The Open Group in the United States and other countries. 


Other company, product, or service names may be trademarks or service marks of others. 


D.2. Source Code For This Document 


The source code for this document is available under the terms of the Common Public License v1.0 
which accompanies this distribution and is available in the appendix Common Public License Version 
1.0. The source code itself is available at 

http://sourceforge.net/project/showfiles.php?group id-119701. 


The source code for this document is maintained in DocBook SGML/XML format. 


і Уч crated DocBook 


with Tid А 
is The Souree for 


Documentation 
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THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS COMMON 
PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE 
PROGRAM CONSTITUTES RECIPIENT’S ACCEPTANCE OF THIS AGREEMENT. 


E.1. Definitions 


"Contribution" means: 


1. in the case of the initial Contributor, the initial code and documentation distributed under this 
Agreement, and 


2. in the case of each subsequent Contributor: 
a. changes to the Program, and 
b. additions to the Program; 
where such changes and/or additions to the Program originate from and are distributed by that particular 
Contributor. A Contribution ’originates’ from a Contributor if it was added to the Program by such 
Contributor itself or anyone acting on such Contributor’s behalf. Contributions do not include additions 


to the Program which: (i) are separate modules of software distributed in conjunction with the Program 
under their own license agreement, and (ii) are not derivative works of the Program. 


"Contributor" means any person or entity that distributes the Program. 


"Licensed Patents " mean patent claims licensable by a Contributor which are necessarily infringed by 
the use or sale of its Contribution alone or when combined with the Program. 


"Program" means the Contributions distributed in accordance with this Agreement. 


"Recipient" means anyone who receives the Program under this Agreement, including all Contributors. 


E.2. Grant of Rights 


1. Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, 
worldwide, royalty-free copyright license to reproduce, prepare derivative works of, publicly 
display, publicly perform, distribute and sublicense the Contribution of such Contributor, if any, and 
such derivative works, in source code and object code form. 


N 


. Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, 
worldwide, royalty-free patent license under Licensed Patents to make, use, sell, offer to sell, import 
and otherwise transfer the Contribution of such Contributor, if any, in source code and object code 
form. This patent license shall apply to the combination of the Contribution and the Program if, at 
the time the Contribution is added by the Contributor, such addition of the Contribution causes such 
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combination to be covered by the Licensed Patents. The patent license shall not apply to any other 
combinations which include the Contribution. No hardware per se is licensed hereunder. 


3. Recipient understands that although each Contributor grants the licenses to its Contributions set 
forth herein, no assurances are provided by any Contributor that the Program does not infringe the 
patent or other intellectual property rights of any other entity. Each Contributor disclaims any 
liability to Recipient for claims brought by any other entity based on infringement of intellectual 
property rights or otherwise. As a condition to exercising the rights and licenses granted hereunder, 
each Recipient hereby assumes sole responsibility to secure any other intellectual property rights 
needed, if any. For example, if a third party patent license is required to allow Recipient to distribute 
the Program, it is Recipient’s responsibility to acquire that license before distributing the Program. 


4. Each Contributor represents that to its knowledge it has sufficient copyright rights in its 
Contribution, if any, to grant the copyright license set forth in this Agreement. 


E.3. Requirements 


A Contributor may choose to distribute the Program in object code form under its own license 
agreement, provided that: 


1. it complies with the terms and conditions of this Agreement; and 
2. its license agreement: 


a. effectively disclaims on behalf of all Contributors all warranties and conditions, express and 
implied, including warranties or conditions of title and non-infringement, and implied 
warranties or conditions of merchantability and fitness for a particular purpose; 


b. effectively excludes on behalf of all Contributors all liability for damages, including direct, 
indirect, special, incidental and consequential damages, such as lost profits; 


c. states that any provisions which differ from this Agreement are offered by that Contributor 
alone and not by any other party; and 


d. states that source code for the Program is available from such Contributor, and informs 
licensees how to obtain it in a reasonable manner on or through a medium customarily used for 
software exchange. 


When the Program is made available in source code form: 


1. it must be made available under this Agreement; and 
2. a copy of this Agreement must be included with each copy of the Program. 
Contributors may not remove or alter any copyright notices contained within the Program. 


Each Contributor must identify itself as the originator of its Contribution, if any, in a manner that 
reasonably allows subsequent Recipients to identify the originator of the Contribution. 
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E.4. Commercial Distribution 


Commercial distributors of software may accept certain responsibilities with respect to end users, 
business partners and the like. While this license is intended to facilitate the commercial use of the 
Program, the Contributor who includes the Program in a commercial product offering should do so in a 
manner which does not create potential liability for other Contributors. Therefore, if a Contributor 
includes the Program in a commercial product offering, such Contributor ("Commercial Contributor") 
hereby agrees to defend and indemnify every other Contributor ("Indemnified Contributor") against any 
losses, damages and costs (collectively "Losses") arising from claims, lawsuits and other legal actions 
brought by a third party against the Indemnified Contributor to the extent caused by the acts or omissions 
of such Commercial Contributor in connection with its distribution of the Program in a commercial 
product offering. The obligations in this section do not apply to any claims or Losses relating to any 
actual or alleged intellectual property infringement. In order to qualify, an Indemnified Contributor must: 
a) promptly notify the Commercial Contributor in writing of such claim, and b) allow the Commercial 
Contributor to control, and cooperate with the Commercial Contributor in, the defense and any related 
settlement negotiations. The Indemnified Contributor may participate in any such claim at its own 
expense. 


For example, a Contributor might include the Program in a commercial product offering, Product X. That 
Contributor is then a Commercial Contributor. If that Commercial Contributor then makes performance 
claims, or offers warranties related to Product X, those performance claims and warranties are such 
Commercial Contributor's responsibility alone. Under this section, the Commercial Contributor would 
have to defend claims against the other Contributors related to those performance claims and warranties, 
and if a court requires any other Contributor to pay any damages as a result, the Commercial Contributor 
must pay those damages. 


E.5. No Warranty 


EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED 
ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER 
EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR 
CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A 
PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the appropriateness of 
using and distributing the Program and assumes all risks associated with its exercise of rights under this 
Agreement, including but not limited to the risks and costs of program errors, compliance with applicable 
laws, damage to or loss of data, programs or equipment, and unavailability or interruption of operations. 


E.6. Disclaimer of Liability 


EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR ANY 
CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT 
LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE 
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PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED 
OF THE POSSIBILITY OF SUCH DAMAGES. 


E.7. General 


If any provision of this Agreement is invalid or unenforceable under applicable law, it shall not affect the 
validity or enforceability of the remainder of the terms of this Agreement, and without further action by 
the parties hereto, such provision shall be reformed to the minimum extent necessary to make such 
provision valid and enforceable. 


If Recipient institutes patent litigation against a Contributor with respect to a patent applicable to 
software (including a cross-claim or counterclaim in a lawsuit), then any patent licenses granted by that 
Contributor to such Recipient under this Agreement shall terminate as of the date such litigation is filed. 
In addition, if Recipient institutes patent litigation against any entity (including a cross-claim or 
counterclaim in a lawsuit) alleging that the Program itself (excluding combinations of the Program with 
other software or hardware) infringes such Recipient’s patent(s), then such Recipient’s rights granted 
under Section 2(b) shall terminate as of the date such litigation is filed. 


All Recipient’s rights under this Agreement shall terminate if it fails to comply with any of the material 
terms or conditions of this Agreement and does not cure such failure in a reasonable period of time after 
becoming aware of such noncompliance. If all Recipient’s rights under this Agreement terminate, 
Recipient agrees to cease use and distribution of the Program as soon as reasonably practicable. 
However, Recipient’s obligations under this Agreement and any licenses granted by Recipient relating to 
the Program shall continue and survive. 


Everyone is permitted to copy and distribute copies of this Agreement, but in order to avoid inconsistency 
the Agreement is copyrighted and may only be modified in the following manner. The Agreement 
Steward reserves the right to publish new versions (including revisions) of this Agreement from time to 
time. No one other than the Agreement Steward has the right to modify this Agreement. IBM is the 
initial Agreement Steward. IBM may assign the responsibility to serve as the Agreement Steward to a 
suitable separate entity. Each new version of the Agreement will be given a distinguishing version 
number. The Program (including Contributions) may always be distributed subject to the version of the 
Agreement under which it was received. In addition, after a new version of the Agreement is published, 
Contributor may elect to distribute the Program (including its Contributions) under the new version. 
Except as expressly stated in Sections 2(a) and 2(b) above, Recipient receives no rights or licenses to the 
intellectual property of any Contributor under this Agreement, whether expressly, by implication, 
estoppel or otherwise. All rights in the Program not expressly granted under this Agreement are reserved. 


This Agreement is governed by the laws of the State of New York and the intellectual property laws of 
the United States of America. No party to this Agreement will bring a legal action under this Agreement 
more than one year after the cause of action arose. Each party waives its rights to a jury trial in any 
resulting litigation. 
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| n dex < <= (strictly less than or equal operator), ?? 
<<= method, ??, ?? 
<= (less than or equal operator(<=), ?? 
<= method, ??, ?? 


Sym bo | S * (multiplication operator), ??, 520 


* method, ??, ?? 


% (integer division operator), ??, 520 жж (power operator), 520 
% method, ??, ?? ** method, ?? 
& (AND logical operator) operator, ?? *-* tracing flag, 77 
& method, ?? + (addition operator), ??, 520 
&& (exclusive OR operator), ?? + method, ??, ??, ?? 
&& method, ?? +++ tracing flag, 77 
> (greater than operator), ?? , (comma) 
> method, ??, ?? as a special character, 16 
>> (strictly greater than operator), 20, ?? as continuation character, 17 
>> method, ??, ?? in CALL instruction, 43 
>>> tracing flag, 77 in function calls, 367 
>>= (strictly greater than or equal operator), in parsing template list, 41, 512 
22 separator of arguments, 43, 367 
>>= method, ??, ?? - (subtraction operator), ??, 520 
>< (greater than or less than operator), ?? - method, ??, ??, ?? 
>< method . (period) 
of Object class, 113 as placeholder in parsing, 503 
of Orderable class, ??, ?? causing substitution in variable names, 32 
of Pointer class, ?? in numbers, 519 
of String class, ??, ?? .CONTEXT, 366 
>.> tracing flag, 77 .ENDOFLINE object, 363 
>= (greater than or equal operator), ?? .ENVIRONMENT object, 363 
>= method, ??, ?? .ERROR object, 364 
>=> tracing flag, 77 .FALSE object, 363 
2A» tracing flag, 77 .INPUT object, 365 
>E> tracing flag, 77 .LINE object, 366 
>F> tracing flag, 77 .LOCAL object, 364 
>L> tracing flag, 78 . METHODS Directory, 366 
2M» tracing flag, 78 .Nil object, 363 
>O> tracing flag, 78 .OUTPUT object, 365 
2 P» tracing flag, 78 .RS (return code) 
2 V» tracing flag, 78 not set during interactive debug, 567 
« (less than operator), ?? .RS object, 366 
« method, ??, ?? .STDERR object, 365 
<> (less than or greater than operator), ?? .STDIN object, 365 
<> method .STDOUT object, 365 
of Object class, 113 .STDQUE object, 365 
of Orderable class, ?? .TRUE object, 363 
of Pointer class, ?? / (division operator), ??, 520 
of String class, ?? / method, ??, ?? 
<<< (strictly less than operator), 20, ?? // (remainder operator), 520 
<< method, ??, ?? // method, ??, ?? 
649 
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: (colon) 
as a special character, 16 
in a label, 26 
:: ATTRIBUTE directive, 81 
:: METHOD directive, 85 
:: REQUIRES directive, 89 
: ROUTINE directive, 91 
CLASS directive, 83 
: CONSTANT directive, 85 
: OPTIONS directive, 88 
DIGITS option, ?? 
FORM option, ?? 
FUZZ option, ?? 
TRACE option, ?? 
; semicolon 
as a special character, 16 
= (equal sign) 
assignment operator, 28 
equal operator, ?? 
immediate debug command, 567 
in DO instruction), 45 
in LOOP instruction), 56 
in parsing template, 506 
= method 
of Object class, 113 
of Orderable class, ?? 
of Pointer class, ?? 
of String class, ?? 
== (strictly equal operator), 20, ??, 523 
== method 
of Object class, 113 
of Orderable class, ?? 
of Pointer class, ?? 
of String class, ?? 
? prefix on TRACE option, 75 
[] method 
of Array class, 219 
of Collection class, 209 
of Directory class, 239 
of IdentityTable class, 281 
of List class, 247 
of Queue class, 257 
of Relation class, 263 
of Stem class, 272 
of Table class, 277 
П- method 
of Array class, 219 
of Bag class, 230 
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of Collection class, 209 
of Directory class, 239 
of IdentityTable class, 281 
of List class, 247 
of Properties class, 253 
of Queue class, 257 
of Relation class, 263 
of Set class, 269 
of Stem class, 273 
of Table class, 277 
V (NOT operator), 21 
V method, 136 
\> (not greater than operator), ?? 
\> method, ??, ?? 
\>> (strictly not greater than operator), ?? 
\>> method, ??, ?? 
\< (not less than operator), ?? 
\< method, ??, ?? 
\<< (strictly not less than operator), ?? 
\<< method, ??, ?? 
\= (not equal operator), ?? 
\= method 
of Object class, 113 
of Pointer class, ?? 
== (not strictly equal operator), 20, ??, 523 
== method, ??, ?? 
of Object class, 113 
of Pointer class, ?? 
| inclusive OR operator, ?? 
| method, ?? 
ll concatenation operator, ?? 
l| method, 113, ?? 
~ (tilde or twiddle), 5, 25 
~~, 25 
^ (NOT operator), 21 
-> (not greater than operator), ?? 
->> (strictly not greater than operator), ?? 
~< (not less than operator), ?? 
—^«« (strictly not less than operator), ?? 
- (not equal operator), ?? 


== (not strictly equal operator), 20, ??, 523 
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АВВЕЕУ function 
description, 375 
example, 376 
using to select a default, 376 
abbrev method 
of String class, 136 
abbreviations with ABBREV function, 375 
ABS function 
description, 376 
example, 376 
abs method 
of String class, 137 
absolute value 
finding using the ABS function, 376 
finding using the abs method, 137 
used with power, 521 
abstract class, definition, 94 
abuttal, ?? 
action taken when a condition is not trapped, 
530 


action taken when a condition is trapped, 527, 


530 
active blocks, 56 
activity, 537 
add external function, 407 
addClass method 
of Package class, 174 
addDays method 
of DateTime class, 299 
of TimeSpan class, 314 
addHours method 
of DateTime class, 300 
of TimeSpan class, 314 
addition operator, ?? 
ADDITIONAL subkeyword 
in a RAISE instruction, 66 
addMicroseconds method 
of DateTime class, 300 
of TimeSpan class, 315 
addMinutes method 
of DateTime class, 300 
of TimeSpan class, 314 
addPackage method 
of Package class, 174 
addPublicClass method 
of Package class, 174 
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addPublicRoutine method 

of Package class, 175 
ADDRESS function 

description, 376 

determining current environment, 376 

example, 376 
ADDRESS instruction 

description, 39 

example, 40 

issuing commands to, 39 

settings saved during subroutine calls, 44 
address setting, 41, 44 
addRoutine method 

of Package class, 175 
addSeconds method 

of DateTime class, 300 

of TimeSpan class, 314 
addWeeks method 

of DateTime class, 299 

of TimeSpan class, 314 
addYears method 

of DateTime class, 299 
Alarm class, 305 
algebraic precedence, 21 
allAt method 

of Relation class, 263 
allIndex method 

of Relation class, 263 
allIndexes method 

of Array class, 219 

of Collection class, 210 

of Directory class, 239 

of IdentityTable class, 281 

of List class, 247 

of Queue class, 257 

of Relation class, 264 

of Stem class, 273 

of Supplier class, 351 

of Table class, 277 
allItems method 

of Array class, 220 

of Collection class, 210 

of Directory class, 239 

of IdentityTable class, 281 

of List class, 247 

of Queue class, 258 

of Relation class, 264 

of Stem class, 273 


of Supplier class, 351 

of Table class, 277 
alphabetical character word options in 
TRACE, 74 
alphabetics 

checking with dataType, 148, 389 

used in symbols, 14 
alphanumerics 

checking with DATATYPE, 389 
alphnumerics 

checking with dataType, 148 
altering 

flow within a repetitive loop, 55 

special variables, 36 

TRACE setting, 423 
alternating exclusive scope access, 544 
AND, logical operator, ?? 
ANDing character strings, 138, 379 
ANY subkeyword 

in a CALL instruction, 42, 527 

in a SIGNAL instruction, 72, 527 
append method 

of Array class, 220 

of List class, 247 

of MutableBuffer class, 330 

of OrederedCollection class, 214 

of Queue class, 258 
аррепа АП method 

of OrderedCollection class, 214 
ARG function 

description, 377 

example, 377 
ARG instruction 

description, 41 

example, 41 
ARG option of PARSE instruction, 60 
ARG subkeyword 

in a PARSE instruction, 41, 59, 511 

in a USE instruction, 78 
args method 

of RexxContextclass, 355 
arguments 

checking with ARG function, 377 

of functions, 41, 367 

of programs, 41 

of subroutines, 41 

passing in messages, 24 


passing to functions, 367, 368 
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retrieving with ARG function, 377 
retrieving with ARG instruction, 41 
retrieving with PARSE ARG instruction, 60 
arguments method 
of Message class, 180 
ARGUMENTS subkeyword 
in a FORWARD instruction, 49 
arithmetic 
basic operator examples, 521 
comparisons, 523 
errors, 524 
exponential notation, 522 
examples, 522 
numeric comparisons example 
examples, 524 
NUMERIC setting, 58 
operator examples, 521 
operators, 18, 519, 520 
overflow, 525 
precision, 520 
underflow, 525 
array 
initialization, 29 
setting up, 32 
Array class, 216 
ARRAY subkeyword 
in a FORWARD instruction, 49 
in a RAISE instruction, 66 
arrayIn method 
of InputStream class, 185 
of Stream class, 190 
arrayOut method 
of OutputStream class, 186 
of Stream class, 191 
assigning data to variables, 60 
assignment 
description, 28, 28 
indicator (=), 28 
of compound variables, 32 
of stems variables, 29 
several assignments, 509 
associative storage, 32 
at method 
of Array class, 220 
of Collection class, 210 
of Directory class, 240 
of IdentityTable class, 281 
of List class, 247 
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of Queue class, 258 

of Relation class, 264 

of Stem class, 273 

of Table class, 278 
attribute 

creation, 81, 85 
ATTRIBUTE subkeyword 

in a METHOD directive, 85 
available method 

of StreamSupplier class, 353 

of Supplier class, 351 


B2X function 
description, 378 
example, 378 
b2x method 
of String class, 137 
backslash, use of, 16, 21 
Bag class, 228 
base class for mixins, 94 
Base option of DATE function, 391 
base64 
decodeBase64 method, 150 
encodeBase64 method, 151 
baseClass method 
of Class class, 124 
baseDate method 
of DateTime class, 301 
bash command environment, 40 
basic operator examples, 521 
BEEP function 
description, 379 
example, 379 
binary 
digits, 13 
strings 
description, 13 
implementation maximum, 14 
nibbles, 13 
to hexadecimal conversion, 137, 378 
BITAND function 
description, 379 
example, 379 
bitAnd method 
of String class, 138 
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BITOR function 
description, 380 
example, 380 
bitOr method 
of String class, 138 
bits checked using DATATYPE function, 389 
bits checked using dataType method, 148 
BITXOR function 
description, 380 
example, 380 
bitXor method 
of String class, 139 
blanks, ?? 
adjacent to special character, 9 
in parsing, treatment of, 502 
removal with STRIP function, 418 
removal with strip method, 159 
boolean operations, 21 
bottom of program reached during execution, 
47 
bounded buffer, 549 
Buffer class, 360 
built-in functions 
ABBREV, 375 
ABS, 376 
ADDRESS, 376 
ARG, 377 
B2X, 378 
BEEP, 379 
BITAND, 379 
BITOR, 380 
BITXOR, 380 
C2D, 381 
C2X, 381 
calling, 42 
CENTER, 382 
CENTRE, 382 
CHANGESTR, 382 
CHARIN, 383 
CHAROUT, 383 
CHARS, 384 
COMPARE, 385 
CONDITION, 385 
COPIES, 387 
COUNTSTR, 387 
D2C, 387 
D2X, 388 
DATATYPE, 389 


DATE, 390 
definition, 42 
DELSTR, 394 
DELWORD, 394 
DIGITS, 395 
DIRECTORY, 395 
ENDLOCAL, 395 
ERRORTEXT, 396 
FILESPEC, 396 
FORM, 397 
FORMAT, 397 
FUZZ, 398 
INSERT, 399 
LASTPOS, 399 
LEFT, 400 
LENGTH, 400 
LINEIN, 400 
LINEOUT, 402 
LINES, 403 
LOWER, 404 
MAX, 404 

MIN, 404 
OVERLAY, 405 
POS, 405 
QUALIFY, 406 
QUEUED, 406 
RANDOM, 406 
REVERSE, 407 
RIGHT, 407 
RXFUNCADD, 407 
RXFUNCDROP, 408 
RXFUNCQUERY, 408 
RXQUEUE, 408 
SETLOCAL, 410 
SIGN, 410 
SOURCELINE, 410 
SPACE, 411 
STREAM, 411 
STRIP, 418 
SUBSTR, 419 
SUBWORD, 419 
SYMBOL, 420 
TIME, 420 
TRACE, 423 
TRANSLATE, 424 
TRUNC, 425 
UPPER, 425 
USERID, 426 
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VALUE, 426 
VAR, 428 
VERIFY, 429 
WORD, 429 
WORDINDEX, 430 
WORDLENGTH, 430 
WORDPOS, 430 
WORDS, 431 
X2B, 431 
X2C, 431 
X2D, 432 
XRANGE, 432 
built-in object 
.CONTEXT object, 366 
.ENDOFLINE object, 363 
.ENVIRONMENT object, 363 
.ERROR object, 364 
.FALSE object, 363 
.INTPUT object, 365 
.LINE object, 366 
.LOCAL object, 364 
. METHODS object, 366 
.Nil object, 363 
.OUTPUT object, 365 
.RS object, 366 
.STDERR object, 365 
.STDIN object, 365 
.STDOUT object, 365 
.STDQUE object, 365 
.TRUE object, 363 
BY phrase of DO instruction, 46 
BY phrase of LOOP instruction, 57 
BY subkeyword 
in a DO instruction, 45, 584 
ina LOOP instruction, 56, 584 


C2D function 
description, 381 
example, 381 

c2d method 
of String class, 139 

C2X function 
description, 381 
example, 381 


c2x method 
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of String class, 140 
CALL instruction 

description, 42 

example, 44 
call method 

of Routine class, 171 
call, recursive, 44 
calls to the Security Manager, 551 
callWith method 

of Routine class, 171 
cancel method 

of Alarm class, 306 
CASELESS subkeyword 

in a PARSE instruction, 59, 510 
caselessAbbrev method 

of String class, 140 
caselessChangeStr method 

of MutableBuffer class, 330 

of String class, 141 
CaselessColumnComparator class, 321 
CaselessComparator class, 319 
caselessCompare method 

of String class, 141 
caselessCompareTo method 

of String class, 142, 142 
caselessCountStr method 

of MutableBuffer class, 330, 330 

of String class, 142, 142 
CaselessDescendingComparator class, 323 
caselessEquals method 

of String class, 142, 142 
caselessLastPos method 

of MutableBuffer class, 330, 330 

of String class, 143, 143 
caselessMatch method 

of MutableBuffer class, 331, 331 

of String class, 143, 143 
caselessMatchChar method 

of MutableBuffer class, 331, 331 

of String class, 144, 144 
caselessPos method 

of MutableBuffer class, 331, 331 

of String class, 144, 144 
caselessWordPos method 

of MutableBuffer class, 332 

of String class, 144 
CENTER function 

description, 382 
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example, 382 
center method 
of String class, 145 
centering a string 
CENTER, 382 
CENTRE, 382 
CENTRE function 
description, 382 
example, 382 
centre method 
of String class, 145 
CHANGESTR function 
description, 382 
example, 382 
changeStr method 
of MutableBuffer class, 332 
of String class, 145 
changing destination of commands, 39 
changing the search order for methods, 100 
character 
definition, 10 
lowercasing using LOWER function, 404 
removal with STRIP function, 419 
removal with strip method, 159 
strings, ANDing, 138, 379 
strings, exclusive-ORing, 139, 380 
strings, ORing, 138, 380 
to decimal conversion, 139, 381 
to hexadecimal conversion, 140, 381 
uppercasing using UPPER function, 425 
character input and output, 557, 568 
character input streams, 558 
character output streams, 558 
CHARIN function 
description, 383 
example, 383 
charIn method 
of InputStream class, 185 
of OutputStream class, 187 
of Stream class, 191 
role in input and output, 558 
CHAROUT function 
description, 383 
example, 384 
charOut method 
of InputStream class, 185 
of OutputStream class, 187 


of Stream class, 191 


role in input and output, 559 
CHARS function 
description, 384 
example, 385 
chars method 
of InputStream class, 185 
of OutputStream class, 187 
of Stream class, 191 
role in input and output, 558 
checking arguments with ARG function, 377 
CircularQueue class, 232 
civilTime method 
of DateTime class, 303 
class 
Alarm class, 305 
Array class, 216 
Bag class, 228 
Buffer class, 360 
CaselessColumnComparator class, 321 
CaselessComparator class, 319 
CaselessDescendingComparator class, 323 
CircularQueue class, 232 
Class class, 122 
ColumnComparator class, 320 
Comparable class, 315 
Comparator class, 318 
DateTime class, 290 
definition, 6 
DescendingComparator class, 322 
Directory class, 237 
IdentityTable class, 280 
InputOutputStream class, 188 
InputStream class, 184 
InvertingComparator class, 325 
List class, 244 
Message class, 178 
Method class, 166 
Monitor class, 327 
MutableBuffer class, 328 
Object class, 111 
Orderable class, 316 
OutputStream class, 186 
Package class, 172 
Pointer class, 358 
Properties class, 251 
Queue class, 255 
RegularExpression class, 339 
Relation class, 262 
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RexxContext class, 354 
RexxQueue class, 345 
Routine class, 169 
Set class, 268 
Stem class, 271 
Stream class, 189 
StreamSupplier class, 352 
String class, 131 
subclasses, 8 
superclasses, 8 
Supplier class, 349 
Table class, 276 
TimeSpan class, 307 
types 
abstract, 94 
metaclass, 94 
mixin, 94 
object, 93 
WeakReference class, 357 
Class class, 122 
class method 
of Object class, 113 
class methods, 93 
CLASS subkeyword 
in a FORWARD instruction, 49 
in a METHOD directive, 85 
in an ATTRIBUTE directive, 81 
classes method 
of Package class, 175 
clauses 
assignment, 27, 28 
commands, 27 
continuation of, 17 
description, 9, 28, 28 
directives, 26 
extended assignment, 28 
instructions, 27 
keyword instructions, 27 
labels, 26 
message instructions, 27 
null, 26 
close method 
of InputStream class, 185 
of OutputStream class, 187 
of Stream class, 192 
CMD command environment, 40 
code page, 10 


codes, error, 593 
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collating sequence using XRANGE, 432 of String class, 146 


Collection class, 209 of TimeSpan class, 312 
organization, 208 comparisons 
Collection classes, 207 description, 20 
COLLECTOR example program, 564 numeric, example, 524 
colon of numbers, 20, 523 
as a special character, 16 of strings, 20, 141, 146, 146, 385 
as label terminators, 26 completed method 
in a label, 26 of Message class, 180 
ColumnComparator class, 320 compound 
combining string and positional patterns, 513 symbols, 32 
comma variable 
as a special character, 16 description, 32 
as continuation character, 17 setting new value, 29 
in CALL instruction, 43 concatenation 
in function calls, 367 abuttal, ?? 
in parsing template list, 41, 512 as concatenation operator, ?? 
separator of arguments, 43, 367 blank, ?? 
command of strings, 19 
alternative destinations, 36 operator 
clause, 27 1.15, 22 
destination of, 39 conceptual overview of parsing, 501 
errors, trapping, 527 concurrency 
issuing to host, 36 alternating exclusive scope access, 544 
COMMAND method, 557 conditional, 544 
of Stream class, 192 default, 540 
comments, 10 early reply, 537 
line comment, 10 GUARD instruction, 51, 544 
standard comment, 10 guarded methods, 544 
Common Public License, 645 isGuarded method, 168 
Comparable class, 315 message objects, 539 
Comparator class, 318 object based, 537 
COMPARE function setGuarded method, 168 
description, 385 setUnguarded method, 169, 544 
example, 385 UNGUARDED option, 544 
compare method condition 
of CaselessColumnComparator class, 322 action taken when not trapped, 530 
of CaselessComparator class, 319 action taken when trapped, 530 
of CaselessDescendingComparator class, ANY, 527 
325 definition, 527 
of ColumnComparator class, 320 ERROR, 527 
of Comparator class, 318 FAILURE, 528 
of DescendingComparator class, 323 HALT, 528 
of InvertingComparator class, 326 information, 45 
of String class, 146 described, 531 
compareTo method LOSTDIGITS, 528 
of Comparable class, 316 NOMETHOD, 528 
of DateTime class, 297 NOSTRING, 528 
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NOTREADY, 528 
NOVALUE, 528 
saved, 45 
saved during subroutine calls, 45 
SYNTAX, 529 
trap information using CONDITION, 385 
trapping of, 527 
traps, notes, 529 
USER, 529 
CONDITION function 
description, 385 
example, 386 
condition method 
of RexxContextclass, 355 
conditional 
loops, 45, 56 
phrase, 586 
conditional concurrency, 544 
conditions 
raising of, 66 
console 
reading from with PULL, 64 
writing to with SAY, 69 
constant symbols, 29 
content addressable storage, 32 
continuation 
character, 17 
clauses, 17 
example, 17 
of data for display, 69 
CONTINUE subkeyword 
in a FORWARD instruction, 49 
control variable, 584 
controlled loops, 584 
conversion 
binary to hexadecimal, 137, 378 
character to decimal, 139, 381 
character to hexadecimal, 140, 381 
conversion functions, 375 
decimal to character, 147, 387 
decimal to hexadecimal, 147, 388 
formating numbers, 151, 397 
hexadecimal to binary, 164, 431 
hexadecimal to character, 165, 431 
hexadecimal to decimal, 165, 432 
COPIES function 
description, 387 
example, 387 
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copies method 
of String class, 146 
copy method 
of Object class, 114 
copying a string using copies, 146, 387 
count from stream, 383 
counting 
words in a mutable buffer, 339 
words in a string, 164, 431 
COUNTSTR function 
description, 387 
example, 387, 387 
countStr method 
of MutableBuffer class, 332 
of String class, 147 
CPL, 645 
create external data queue, 408 
create method 
of RexxQueue class, 347 
current method 
of Monitor class, 328 


D2C function 
description, 387 
example, 388 
implementation maximum, 388 

d2c method 
of String class, 147 

D2X function 
description, 388 
example, 388 
implementation maximum, 388 

d2x method 
of String class, 147 

data 
abstraction, 8 
encapsulation, 4 
modularization, 2 
objects, 17 
terms, 18 

DATATYPE function 
description, 389 
example, 390 

dataType method 
of String class, 148 
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date and version of the language processor, 62 
DATE function 
description, 390 
example, 392 
date method 
of DateTime class, 304 
DateTime class, 290 
day method 
of DateTime class, 298 
dayMicroseconds method 
of DateTime class, 299 
dayMinutes method 
of DateTime class, 298 
dayName method 
of DateTime class, 302 
days method 
of TimeSpan class, 312 
Days option of DATE function, 391 
daySeconds method 
of DateTime class, 298 
daysInMonth method 
of DateTime class, 305 
daysInYear method 
of DateTime class, 305 
debug interactive, 73 
decimal 
integer, 519 
to character conversion, 147, 387 
to hexadecimal conversion, 147, 388 
decodeBase64 method 
of String class, 150 
default 
character streams, 557 
concurrency, 540 
environment, 35 
search order for methods, 100 
selecting with ABBREV function, 375 
selecting with abbrev method, 136 
selecting with caselessAbbrev method, 140 
defaultName method 
of Class class, 124 
of Object class, 114 
define method 
of Class class, 124 
definedMethods method 
of Package class, 175 
delayed state 
description, 527 
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of NOTREADY condition, 565 
delete class method 

of RexxQueue class, 347 
delete method 

of Class class, 125 

of MutableBuffer class, 332 

of RexxQueue class, 347 
deleting 

part of a string, 150, 394 

words from a mutablebuffer, 333 

words from a string, 150, 394 
DELSTR function 

description, 394 

example, 394 
delstr method 

of MutableBuffer class, 333 

of String class, 150 
DELWORD function 

description, 394 

example, 394 
delWord method 

of MutableBuffer class, 333 

of String class, 150 
derived names of variables, 32 
DescendingComparator class, 322 
description method 

of Stream class, 198 
DESCRIPTION subkeyword 

in a RAISE instruction, 66 
destination method 

of Monitor class, 328 
difference method 

of Bag class, 230 

of Collection class, 210 

of IdentityTable class, 282 

of OrderedCollection class, 215 

of Table class, 278 
differencemethod 

of Relation class, 264 
DIGITS function 

description, 395 

example, 395 
digits method 

of Package class, 175 

of RexxContextclass, 356 
DIGITS option of NUMERIC instruction, 519 
DIGITS subkeyword 

in a NUMERIC instruction, 58, 520 


dimension method 
of Array class, 221 
directives 
ATTRIBUTE, 81 
CLASS, 83 
z CONSTANT, 85 
: METHOD, 85 
::OPTIONS, 88 
:REQUIRES, 89 
ROUTINE, 91 
Directory class, 237 
DIRECTORY function 
description, 395 
example, 395 
division operator, ?? 
dllfunctions, 435 
DO instruction 
description, 45 
example, 583 
drop external function, 408 
DROP instruction 
description, 46 
example, 46 
DROP keyword 
ina RXSUBCOM command, 577 
duration method 
of TimeSpan class, 312 
dyadic operators, 18 
dynamic link library (RexxUtil), 435 


early reply, 68, 537 
elapsed method 

of DateTime class, 304 
elapsed-time clock 

measuring intervals with, 420 

saved during subroutine calls, 45 
ELSE 

as free standing clause, 39 
ELSE subkey word 

in an IF instruction, 52 
empty method 

of Array class, 221 

of Directory class, 240 

of List class, 247 

of Queue class, 258 
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of Relation class, 264 
of RexxQueue class, 347 
of Stem class, 274 
encapsulation of data, 4 
encodeBase64 method 
of String class, 151 
END 
as free standing clause, 39 
END clause 
specifying control variable, 584 
END subkeyword 
in a DO instruction, 45 
in a LOOP instruction, 56 
in a SELECT instruction, 70 
ENDLOCAL function 
description, 395 
example, 396 
engineering notation, 523 
ENGINEERING subkeyword 
in a NUMERIC instruction, 58 
enhanced method 
of Class class, 125 
entry method 
of Directory class, 240 
environment, 39 
addressing of, 40 
default, 41 
determining current using ADDRESS 
function, 376 
equal 
operator, ?? 
sign 
in parsing templates, 505, 506 
to indicate assignment, 15, 28 
equality, testing of, 20 
equals method 
of String class, 151 
error 
definition, 36 
during execution of functions, 374 
during stream input and output, 565 
from commands, 36 
messages 
list, 593 
retrieving with ERRORTEXT, 593 
syntax, 593 
traceback after, 75 
trapping, 527 
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error codes, 593 
error messages and codes, 593 
ERROR subkeyword 
in a CALL instruction, 42, 527, 532 
in a RAISE instruction, 66 
in a SIGNAL instruction, 72, 527, 532 
errorCondition method 
of Message class, 180 
ERRORTEXT function 
description, 396 
example, 396 
European option of DATE function, 391 
europeanDate method 
of DateTime class, 301 
evaluation of expressions, 18 
examples 
: ATTRIBUTE directive 
EXTERNAL option, 82 
: CLASS directive, 84 
: METHOD directive, 86 
EXTERNAL option, 87 
: ROUTINE directive, 91 
EXTERNAL option, 92 
ABBREV function, 376 
abbrev method, 137, 140 
ABS function, 376 
abs method, 137 
ADDRESS function, 376 
ADDRESS instruction, 40 
allIndexes method, 219 
allItems method, 220 
append method, 220 
ARG function, 377 
ARG instruction, 41 


arithmetic methods of DateTime class, 297, 


311 

arithmetic methods of String class, 134 
at method, 221 

B2X function, 378 

b2x method, 138 

basic operator examples, 521 
BEEP function, 379 
BITAND function, 379 
bitAnd method, 138 

BITOR function, 380 

bitOr method, 139 

BITXOR function, 380 
bitXor method, 139 
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C2D function, 381 
c2d method, 139 
C2X function, 381 
c2x method, 140 
CALL instruction, 44 
caselessChangeStr method, 141 
caselessCompareTo method, 142 
caselessEquals method, 142 
caselessLastPos method, 143 
caselessMatch method, 143 
caselessMatchChar method, 144 
caselessPos method, 144 
CENTER function, 382 
center method, 145 
CENTRE function, 382 
centre method, 145 
CHANGESTR function, 382 
changeStr method, 145 
CHARIN function, 383 
CHAROUT function, 384 
CHARS function, 385 
COLLECTOR program, 564 
combining positional pattern and parsing 
into words, 509 
combining string and positional patterns, 
213 
combining string pattern and parsing into 
words, 508 
command method 
OPEN option, 194 
QUERY DATETIME option, 196 
QUERY EXISTS option, 196 
QUERY HANDLE option, 196 
SEEK option, 196 
COMPARE function, 385 
compare method, 141, 146 
compareTo method, 146 
comparison methods of String class, 134 
concatenation methods of String class, 136 
CONDITION function, 386 
continuation, 17 
COPIES function, 387 
copies method, 146 
copy method, 114 
COUNTSTR function, 387, 387 
countStr method, 142, 147 
D2C function, 388 
d2c method, 147 


D2X function, 388 
d2x method, 148 
DATATYPE function, 390 
dataType method, 149 
DATE function, 392 
decodeBase64 method, 150 
defaultName method, 124 
define method, 124 
delete method, 125 
DELSTR function, 394 
delStr method, 150 
DELWORD function, 394 
delWord method, 150, 150 
DIGITS function, 395 
dimension method, 221 
DIRECTORY function, 395 
DO instruction, 583 
DROP instruction, 46 
empty method, 221 
encodeBase64 method, 151 
ENDLOCAL function, 396 
enhanced method, 125 
equals method, 151 
ERRORTEXT function, 396 
EXIT instruction, 47 
exponential notation, 522 
EXPOSE instruction, 48 
expressions, 22 
FILECOPY program, 564 
FILESPEC function, 397 
first method, 221 
FORM function, 397 
FORMAT function, 398 
format method, 151 
FORWARD instruction, 50 
FUZZ function, 399 
GUARD instruction, 51 
hasIndex method, 222 
hasItem method, 222 
id method, 126 
IF instruction, 52 
index method, 222 
inherit method, 126 
INSERT function, 399 
insert method 

of List class, 249 

of Queue class, 259 

of String class, 152 
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INTERPRET instruction, 53, 54 
isEmpty method, 223 
items method, 223 
ITERATE instruction, 55 
last method, 223 
LASTPOS function, 399 
lastPos method, 153, 334 
LEAVE instruction, 56 
LEFT function, 400 

left method, 153 
LENGTH function, 400 
length method, 154 

line comments, 10 
LINEIN function, 401 
LINEOUT function, 402 
LINES function, 403 
logical methods of String class, 136 
LOOP instruction, 583 
lower function, 404 

lower method, 154 
makeArray method, 223 
match method, 155 
matchChar method, 155 
MAX function, 404 

max method, 156 
message instructions, 34 
metaclass, 95 

method method, 127 
methods method, 128 
MIN function, 404 

min method, 156 
mixinClass method, 128 
new method, 129 

next method, 224 

NOP instruction, 58 
notify method, 181 
numeric comparisons, 524 
objectName= method, 116 
of Alarm class, 307 

of Array class, 228 

of Bag class, 232 

of CircularQueue class, 236 
of Directory class, 243 

of Message class, 182 

of method, 218, 219 

of Monitor class, 328 

of program, 564 

of Relation class, 267 
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of Supplier class, 352 
open method, 201 
operator examples, 521 
OVERLAY function, 405 
overlay method, 156 
PARSE instruction, 61 
parsing instructions, 511 
parsing multiple strings in a subroutine, 513 
period as a placeholder, 503 
POS function, 405 
pos method, 157, 336 
previous method, 224 
PROCEDURE instruction, 63 
PULL instruction, 65 
PUSH instruction, 65 
put method, 225 
query method, 202 
QUEUE instruction, 66 
QUEUED function, 406 
RAISE instruction, 67 
RANDOM function, 406 
RegularExpression class, 341, 343, 344, 
344 
remove method, 225 
removeltem method, 225 
replaceAt method, 157 
REPLY instruction, 68 
REVERSE function, 407 
reverse method, 158 
RIGHT function, 407 
right method, 158 
RXFUNCADD function, 408 
RXFUNCDROP function, 408 
RXFUNCQUERY function, 408 
RXFUNCQUEUE function, 409 
RxMessageBox, 440 
SAY instruction, 70 
section method, 226 
seek method, 205 
SELECT instruction, 71 
set operations 

concepts, 286 

eliminating duplicates, 287 

principals, 287 

with duplicates, 288 
SETLOCAL function, 410 
SIGL, special variable, 534 
SIGN function, 410 
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sign method, 158 
SIGNAL instruction, 73 


simple templates, parsing, 501 
SOURCELINE function, 411 


SPACE function, 411 
space method, 158 
special characters, 16 
standard comments, 11 
start method, 182 


STREAM function, 415, 416 


STRIP function, 419 

strip method, 159 
subClass method, 130 
SUBSTR function, 419 
subStr method, 160 
SUBWORD function, 419 
subWord method, 160 
superClass method, 130 
superClasses method, 130 
supplier method, 227 
SYMBOL function, 420 
SysCurPos, 446 
SysDriveInfo, 447 
SysDriveMap, 448 
SysDumpVariables, 449 
SysFileCopy, 449 
SysFileDelete, 450 
SysFileMove, 452 
SysFileSearch, 453 
SysFileSystemType, 454 
SysFileTree, 457 
SysGetDefaultPrinter, 498 
SysGetErrortext, 461 
SysGetFileDateTime, 462 
SysGetMessage, 463 
SysGetMessageX, 464 
SysGetPrinters, 498 
SysIni, 466 

SysMkDir, 473 
SysRmDir, 479 
SysSearchPath, 480 
SysSetDefaultPrinter, 498 
SysSetFileDateTime, 481 
SysSleep, 483 
SysStemCopy, 485 
SysStemDelete, 485 
SysStemSort, 487 
SysTempFileName, 489 


SysTextScreenRead, 490 
SysTextScreenSize, 490 
templates containing positional patterns, 
505 
templates containing string patterns, 504 
TIME function, 422, 423 
toString method, 227 
TRACE function, 424 
TRACE instruction, 76 
TRANSLATE function, 424 
translate method, 161 
TRUNC function, 425 
trunc method, 161 
uninherit method, 131 
upper function, 425 
upper method, 162 
USE instruction, 79 
using a variable as a string pattern, 510 
using an expression as a positional pattern, 
510 
VALUE function, 426, 428 
VAR function, 428 
VERIFY function, 429 
verify method, 162, 338 
WORD function, 429 
word method, 163 
WORDINDEX function, 430 
wordIndex method, 163 
WORDLENGTH function, 430 
wordLength method, 163 
WORDPOS function, 430 
wordPos method, 144, 164 
WORDS function, 431 
words method, 164 
X2B function, 431 
x2b method, 164 
X2C function, 432 
x2c method, 165 
X2D function, 432, 432 
x2d method, 165 
XRANGE function, 433 
exception conditions saved during subroutine 
calls, 44 
exclusive OR operator, ?? 
exclusive-ORing character strings together, 
139, 380 
executable method 
of RexxContextclass, 356 
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execution 

by language processor, 1 

of data, 53 
exists method 

of RexxQueue class, 347 
EXIT instruction 

description, 47 

example, 47 
EXIT subkeyword 

in a RAISE instruction, 66 
exponential notation 

description, 522 

example, 14, 522 
exponentiation 

description, 522 

operator, ?? 
EXPOSE instruction 

description, 48 

example, 48 
EXPOSE option of PROCEDURE instruction, 
62 
EXPOSE subkeyword 

in a PROCEDURE instruction, 62 
exposed variable, 62 
expressions 

evaluation, 18 

examples, 22 

parsing of, 61 

results of, 18 

tracing results of, 75 
extended assignments, 28 
external character streams, 557 
external data queue 

counting lines in, 406 

creating and deleting queues, 408 

description, 559 

naming and querying queues, 408 

reading from with PULL, 64 

RXQUEUE function, 408 

writing to with PUSH, 65 

writing to with QUEUE, 65 
external functions 

description, 368 

functions 

description, ?? 

search order, 368 
external routine, 42 
EXTERNAL subkey word 
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in a ROUTINE directive, 91 >>>,77 


LIBRARY routine, 91 >>! 
REGISTERED routine, 91 >=> 77 
external subroutines, 368 >А>,77 
external variables >E>, 77 
access with VALUE function, 426 >F>, 77 
extracting >L>, 78 
substring, 159, 419 >M>, 78 
word from a mutable buffer, 339 >O>, 78 
word from a string, 163, 429 >P>, 78 
words from a mutable buffer, 339 >V>, 78 
words from a string, 164, 431 ж.ж 77 
extracting words with subWord, 160, 337 +++, 77 


flow of control 
unusual, with CALL, 527 


F unusual, with SIGNAL, 527 
with CALL and RETURN construct, 42 
FAILURE subkeyword with DO construct, 45 
in a CALL instruction, 42, 528, 532 with IF construct, 52 
in a RAISE instruction, 66 with LOOP construct, 56 
in a SIGNAL instruction, 72, 528, 532 with SELECT construct, 70 
failure, definition, 36 flush method 
FIFO (first-in/first-out) stacking, 66 of Stream class, 198 
file name, extension, path of program, 61 FOR phrase of DO instruction, 46 
FILECOPY example program, 564 FOR phrase of LOOP instruction, 57 
files, 557 FOR subkeyword 
FILESPEC function in a DO instruction, 45 
description, 396 in a LOOP instruction, 56 
example, 397 FOREVER phrase of DO instruction, 45 
findClass method FOREVER phrase of LOOP instruction, 56 
of Package class, 175 FOREVER repetitor on DO instruction, 46 
finding FOREVER repetitor on LOOP instruction, 57 
mismatch using caselessCompare, 141 FOREVER subkeyword 
mismatch using compare, 146, 385 in a DO instruction, 45, 583, 586 
mismatch using compareTo, 146 in a LOOP instruction, 56, 583, 586 
string in a MutableBuffer, 335 FORM function 
string in another string, 157, 405 description, 397 
string length, 154, 400 example, 397 
word length, 163, 339, 430 form method 
findRoutine method of Package class, 176 
of Package class, 176 of RexxContextclass, 356 
first method FORM option of NUMERIC instruction, 58 
of Array class, 221 FORM subkeyword 
of List class, 248 in a NUMERIC instruction, 58, 523 
of Queue class, 258 FORMAT function 
firstItem method description, 397 
of List class, 248 example, 398 
flag, tracing format method 


ooRexx Reference Version 4.0.0 665 


of String class, 151 
formatting 

numbers for display, 151, 397 

numbers with trunc, 161, 425 

of output during tracing, 77 

text centering, 145, 382 

text left justification, 153, 400 

text right justification, 158, 407 

text spacing, 158, 411 
FORWARD instruction 

description, 49 

example, 50 
fromBaseDate method 

of DateTime class, 295 
fromCivilTime method 

of DateTime class, 294 

of TimeSpan class, 310 
fromDays method 

of TimeSpan class, 309 
fromEuropeanDate method 

of DateTime class, 293 
fromHours method 

of TimeSpan class, 309 
fromIsoDate method 

of DateTime class, 295 
fromLongTime method 

of DateTime class, 294 

of TimeSpan class, 310 
fromMicroseconds method 

of TimeSpan class, 309 
fromMinutes method 

of TimeSpan class, 309 
fromNormalDate method 

of DateTime class, 292 
fromNormalTime method 

of DateTime class, 294 

of TimeSpan class, 310 
fromOrderedDate method 

of DateTime class, 293 
fromSeconds method 

of TimeSpan class, 309 
fromStandardDate method 

of DateTime class, 293 
fromStringFormat method 

of TimeSpan class, 310 
fromTicks method 

of DateTime class, 295 
fromUsaDate method 
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of DateTime class, 294 
fromUTCIsoDate method 

of DateTime class, 295 
Full option of DATE function, 391 
Full option of Time function, 421 
fullDate method 

of DateTime class, 303 
functions, 367 

ABBREV, 375 

ABS, 376 

ADDRESS, 376 

ARG, 377 

B2X, 378 

BEEP, 379 

BITAND, 379 

BITOR, 380 

BITXOR, 380 

built-in, 375 

built-in, description, 375 

C2D, 381 

C2X, 381 

call, definition, 367 

calling, 367 

CENTER, 382 

CENTRE, 382 

CHANGESTR, 382 

CHARIN, 383 

CHAROUT, 383 

CHARS, 384 

COMPARE, 385 

CONDITION, 385 

COPIES, 387 

COUNTSTR, 387 

D2C, 387 

D2X, 388 

DATATYPE, 389 

DATE, 390 

definition, 367 

DELSTR, 394 

DELWORD, 394 

description, 367 

DIGITS, 395 

DIRECTORY, 395 

ENDLOCAL, 395 

ERRORTEXT, 396 

external, 368 

FILESPEC, 396 


forcing built-in or external reference, 368 


ooRexx Reference Version 4.0.0 


FORM, 397 WORDINDEX, 430 


FORMAT, 397 WORDLENGTH, 430 
FUZZ, 398 WORDPOS, 430 
INSERT, 399 WORDS, 431 

internal, 368 X2B, 431 

LASTPOS, 399 X2C, 431 

LEFT, 400 X2D, 432 

LENGTH, 400 XRANGE, 432 

LINEIN, 400 FUZZ 

LINEOUT, 402 controlling numeric comparison, 524 
LINES, 403 instruction, 59, 524 
logical bit operations, 379, 380, 380 FUZZ function 

LOWER, 404 description, 398 

MAX, 404 example, 399 

MIN, 404 fuzz method 

numeric arguments of, ?? of Package class, 176 
OVERLAY, 405 of RexxContextclass, 356 
POS, 405 FUZZ subkeyword 
QUALIFY, 406 in a NUMERIC instruction, 58, 524 
QUEUED, 406 

RANDOM, 406 

return from, 69 

REVERSE, 407 G 

RIGHT, 407 


RXFUNCADD, 407 general concepts, 1, 39 


RXFUNCDROP, 408 get method 

RXFUNCQUERY, 408 of RexxQueue class, 347 
RXQUEUE, 408 l GET subkeyword 

SETLOCAL, 410 in an ATTRIBUTE directive, 81 
SIGN, 410 getBufferSize method 


SOURCELINE. 410 of MutableBuffer class, 333 


SPACE, 411 getLogical method 

STREAM, 411 of Properties class, 253 

STRIP, 418 getProperty method 

SUBSTR, 419 of Properties class, 254 

SUBWORD, 419 getting value with VALUE, 426 
SYMBOL, 420 getWhole method 

TIME, 420 of Properties class, 254 

TRACE, 423 global variables 

TRANSLATE, 424 access with VALUE function, 426 
TRUNC, 425 GOTO, unusual, 527 

UPPER, 425 greater than operator, ?? 

USERID, 426 greater than operator (>), ?? 

VALUE, 426 greater than or equal operator, ?? 

VAR, 428 greater than or equal to operator (>=), ?? 
variables in, 62 greater than or less than operator, ?? 
VERIFY, 429 greater than or less than operator (><), ?? 
WORD, 429 group, DO, 583 
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grouping instructions to run repetitively, 45, 
56 
GUARD instruction 
description, 51 
example, 51 
guarded methods, 544 
GUARDED subkeyword 
in a METHOD directive, 85 
in an ATTRIBUTE directive, 81 


HALT subkeyword 

in a CALL instruction, 42, 528, 532 

in a SIGNAL instruction, 72, 528, 532 
halt, trapping, 528 
hasEntry method 

of Directory class, 240 
hasError method 

of Message class, 181 
hashCode method 

of DateTime class, 299 

of Object class, 114 

of String class, 152 

of TimeSpan class, 313 
hasIndex method 

of Array class, 222 

of Bag class, 230 

of Collection class, 210 

of Directory class, 240 

of IdentityTable class, 282 

of List class, 248 

of Queue class, 258 

of Relation class, 264 

of Stem class, 274 

of Table class, 278 
hasItem method 

of Array class, 222 

of Collection class, 210 

of Directory class, 240 

of IdentityTable class, 282 

of List class, 248 

of Queue class, 258 

of Relation class, 265 

of Stem class, 274 

of Table class, 278 
hasMethod method 
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of Object class, 115 
hexadecimal 
checking with dataType, 148, 389 
digits, 13 
strings 
description, 13 
implementation maximum, 13 
to binary, converting with X2B, 164, 431 
to character, converting with X2C, 165, 431 
to decimal, converting with X2D, 165, 432 
host commands 
issuing commands to underlying operating 
system, 36 
hours calculated from midnight, 421 
hours method 
of DateTime class, 298 
of TimeSpan class, 312 


id method 

of Class class, 126 
identityHash method 

of Object class, 115 
IdentityTable class, 280 
IF instruction 

description, 52 

example, 52 
implementation maximum 

binary strings, 14 

D2C function, 388 

d2c method, 147 

D2X function, 388 

d2x method, 148 

hexadecimal strings, 13 

literal strings, 13 

numbers, 15 

TIME function, 423 
implied semicolons, 16 
importedClasses method 

of Package class, 176 
importedRoutines method 

of Package class, 176 
imprecise numeric comparison, 523 
inclusive OR operator, ?? 
indentation during tracing, 77 


index method 
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of Array class, 222 
of Collection class, 211 
of Directory class, 241 
of IdentityTable class, 282 
of List class, 248 
of Queue class, 259 
of Relation class, 265 
of Stem class, 274 
of StreamSupplier class, 354 
of Supplier class, 351 
of Table class, 278 
indirect evaluation of data, 53 
inequality, testing of, 20 
infinite loops, 45, 56, 584 
information hiding, 5 
inherit method 
of Class class, 126 
INHERIT subkeyword 
іп a CLASS directive, 83 
inheritance, 8 
init method 
of Alarm class, 306 
of CaselessColumnComparator class, 322 
of CircularQueue class, 233 
of ColumnComparator class, 321 
of DateTime class, 296 
of InvertingComparator class, 327 
of Monitor class, 328 
of Object class, 115 
of RegularExpression class, 342 
of RexxQueue class, 348 
of Stream class, 198 
of StreamSupplier class, 354 
of Supplier class, 351 
of TimeSpan class, 310 
initialization 
of arrays, 30 
of compound variables, 30 
input and output 
functions 
CHARIN, 383 
CHAROUT, 383 
CHARS, 384 
LINEIN, 400 
LINEOUT, 402 
LINES, 403 
STREAM, 411 
model, 557 
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streams, 557 
input from the user, 557 
input object, 365 
input streams, 558 
input to PULL from STDIN, 64 
input to PULL from the keyboard, 64 
input, errors during, 565 
InputOutputStream class, 188 
InputStream class, 184 
INSERT function 

description, 399 

example, 399 
insert method 

of List class, 248 

of MutableBuffer class, 333 

of Queue class, 259 

of String class, 152 
inserting a string into another, 152, 399 
instance methods, 93 
instanceMethod method 

of Object class, 115 
instanceMethods method 

of Object class, 115 
instances 

definition, 6 
instructions 

ADDRESS, 39 

ARG, 41 

CALL, 42 

definition, 27 

DO, 45 

DROP, 46 

EXIT, 47 

EXPOSE, 48 

FORWARD, 49 

GUARD, 51, 544 

IF, 52 

INTERPRET, 53 

ITERATE, 55 

keyword, 27 

description, 39 

LEAVE, 55 

LOOP, 56 

message, 27, 34 

NOP, 57 

NUMERIC, 58 

OPTIONS, 59 

PARSE, 59 


parsing, summary, 511 
PROCEDURE, 62 
PULL, 64 
PUSH, 65 
QUEUE, 65 
RAISE, 66 
REPLY, 68 
RETURN, 69 
SAY, 69 
SELECT, 70 
SIGNAL, 72 
TRACE, 73 
USE, 78 
integer 
arithmetic, 519 
division 
description>, 519, 521 
integer division operator, ?? 
interactive debug, 73 
internal 
functions 
return from, 69 
variables in, 62 
routine, 42 
INTERPRET instruction 
description, 53 
example, 53, 54 
interpretive execution of data, 53 
intersection method 
of Bag class, 231 
of Collection class, 211 
of OrderedCollection class, 215 
of Relation class, 265 
of Set class, 269 
InvertingComparator class, 325 
invoking 
built-in functions, 42 
routines, 42 
isA method 
of Object class, 116 
isEmpty method 
of Array class, 223 
of Directory class, 241 
of IdentityTable class, 282 
of List class, 249 
of Queue class, 259 
of Relation class, 265 
of Stem class, 274 
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of Table class, 278 
isGuarded method 

of Method class, 168 
isInstanceOf method 

of Object class, 116 
isLeapyear method 

of DateTime class, 305 
isNull method 

of Pointer class, 359 
isoDate method 

of DateTime class, 300 
isPrivate method 

of Method class, 168 
isProtected method 

of Method class, 168 
isSubclassOf method 

of Class class, 126 
item method 

of StreamSupplier class, 354 

of Supplier class, 351 
items method 

of Array class, 223 

of Collection class, 211 

of Directory class, 241 

of IdentityTable class, 282 

of List class, 249 

of Queue class, 260 

of Relation class, 265 

of Stem class, 274 

of Table class, 279 
ITERATE instruction 

description, 55 


example, 55 


justification, text right, RIGHT function, 407 
justification, text right, RIGHT method, 158 


keyword 
conflict with commands, 571 
description, 39 


mixed case, 39 
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reservation of, 571 


label 
as target of CALL, 42 
as target of SIGNAL, 72 
description, 26 
duplicate, 73 
in INTERPRET instruction, 53 
search algorithm, 72 
language 
processor date and version, 62 
processor execution, | 
structure and syntax, 9 
Language (local) option of DATE function, 
391 
languageDate method 
of DateTime class, 301 
last method 
of Array class, 223 
of List class, 249 
of Queue class, 260 
lastItem method 
of List class, 250 
LASTPOS function 
description, 399 
example, 399 
lastPos method 
of MutableBuffer class, 334 
of String class, 153 
leading 
leading whitespace removal with STRIP 
function, 418 
whitespace removal with strip method, 159 
Zeros 
adding with RIGHT function, 407 
adding with right method, 158 
removing with STRIP function, 418 
removing with strip method, 159 
LEAVE instruction 
description, 55 
example, 56 
leaving your program, 47, 47 
LEFT function 
description, 400 
example, 400 
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left method 

of String class, 153 
LENGTH function 

description, 400 

example, 400 
length method 

of MutableBuffer class, 334 

of String class, 154 
length positional pattern 

positional patterns 

length, 507 

less than operator (<), ?? 
less than or equal to operator (>=), ?? 
less than or greater than operator (<>), ?? 
LIBRARY subkeyword 

in a REQUIRES directive, 89 
License, Common Public, 645 
License, Open Object Rexx, 645 
LIFO (last-in, first-out) stacking, 65 
line input and output, 557 
line method 

of RexxContextclass, 356 
LINEIN function 

description, 400 

example, 401 
lineIn method 

of InputStream class, 185 

of OutputStream class, 187 

of RexxQueue class, 348 

of Stream class, 198 

role in input and output, 558 
LINEIN option of PARSE instruction, 60 
LINEIN subkeyword 

in a PARSE instruction, 59, 511 
LINEOUT function 

description, 402 

example, 402 
lineOut method 

of InputStream class, 185 

of OutputStream class, 187 

of RexxQueue class, 348 

of Stream class, 199 

role in input and output, 559 
lines 

from a program retrieved with 

SOURCELINE, 410 

from stream, 60 
LINES function 


description, 403 

example, 403 

from stream, 400 

remaining in stream, 403 
lines method 

of InputStream class, 185 

of OutputStream class, 187 

of Stream class, 199 

role in input and output, 558 
List class, 244 
literal 

description, 12 

implementation maximum, 13 

patterns, 504 
LOAD keyword 

in a RXSUBCOM command, 578 
load method 

of Properties class, 253, 254 
loadExternalMethod method 

of Method class, 167 
loadExternalRoutine method 

of Routine class, 171 
loadLibrary method 

of Package class, 176 
loadPackage method 

of Package class, 177 
locating 

string in a MutableBuffer, 335 

string in another string, 157, 405 

word in another mutable buffer, 339 

word in another string, 163, 429 
logical 

operations, 21 
logical bit operations 

BITAND, 379 

BITOR, 380 

BITXOR, 380 
logical NOT character, 16 
logical OR operator, 15 
longTime method 

of DateTime class, 303 
LOOP instruction 

description, 56 

example, 583 
loops 

active, 55 

execution model, 588, 589 


modification of, 55 
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over collections, 585 

repetitive, 583 

termination of, 55 
LOSTDIGITS subkeyword 

in a CALL instruction, 532 

in a SIGNAL instruction, 72, 528, 532 
LOWER function 

description, 404 
lower method 

of MutableBuffer class, 334 

of String class, 154 
LOWER subkeyword 

in a PARSE instruction, 59, 510 
lowercase translation 

with PARSE LOWER, 60 


makeArray method 
of Array class, 223 
of CircularQueue class, 234 
of Collection class, 211 
of Directory class, 241 
of IdentityTable class, 283 
of List class, 250 
of MapCollection class, 214 
of MutableBuffer class, 334 
of Queue class, 260 
of Relation class, 265 
of RexxQueue class, 348 
of Stem class, 274 
of Stream class, 199 
of String class, 154 
of Table class, 279 
makeString method 
of Array class, 224 
of String class, 155 
Map Collection classes 
Directory class, 237 
IdentityTable class, 280 
Properties class, 251 
Relation class, 262 
Stem class, 271 
Table class, 276 
MapCollection class, 212 
match method 
of MutableBuffer class, 335 


ooRexx Reference Version 4.0.0 


of RegularExpression class, 342 


of String class, 155 
matchChar method 

of MutableBuffer class, 335 

of String class, 155 
MAX function 

description, 404 

example, 404 
max method 

of String class, 156 
maxDate method 

of DateTime class, 292 
Message class, 178 


message instructions, 27, 34 


message sequence instructions, 34 


MESSAGE subkeyword 


in a FORWARD instruction, 49 


message-send operator (~), 5 
messageName method 
of Message class, 181 
messages, 5 
messages to objects 
operator as message, 18 
-, using, 25 
~~, using, 25 
messages, error, 593 
metaClass method 
of Class class, 127 
METACLASS subkeyword 
іп a CLASS directive, 83 
metaclasses, 94 
method 
до, 27, 2? 
&, 2? 
&&, ?? 
222,11 
SO 
>>-, 25 17 
>< 
of Object class, 113 
of Orderable class, ?? 
of Pointer class, ?? 


of String class, ?? 


>- 00 
<,729,77 
<> 


of Object class, 113 


of Orderable class, ?? 
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of Pointer class, ?? 
of String class, ?? 
<<, 27,27 
<<- T. 
<- пи 
ж 99 99 
pas ee 
жж 99 
E 
+, ??, ??, ?? 
2.99 99 99 
22. 22,21 
LICHE 
/[,22, 22 


of Object class, 113 

of Orderable class, ?? 

of Pointer class, ?? 

of String class, ?? 

of Object class, 113 

of Orderable class, ?? 

of Pointer class, ?? 

of String class, ?? 
abbrev method 

of String class, 136 
abs method 

of String class, 137 
addClass method 

of Package class, 174 
addDays method 

of DateTime class, 299 

of TimeSpan class, 314 
addHours method 

of DateTime class, 300 

of TimeSpan class, 314 
addMicroseconds method 

of DateTime class, 300 

of TimeSpan class, 315 
addMinutes method 

of DateTime class, 300 

of TimeSpan class, 314 
addPackage method 

of Package class, 174 
addPublicClass method 

of Package class, 174 
addPublicRoutine method 

of Package class, 175 
addRoutine method 

of Package class, 175 
addSeconds method 


of DateTime class, 300 

of TimeSpan class, 314 
addWeeks method 

of DateTime class, 299 

of TimeSpan class, 314 
addYears method 

of DateTime class, 299 
allAt method 

of Relation class, 263 
allIndex method 

of Relation class, 263 
allIndexes method 

of Array class, 219 

of Collection class, 210 

of Directory class, 239 

of IdentityTable class, 281 

of List class, 247 

of Queue class, 257 

of Relation class, 264 

of Stem class, 273 

of Supplier class, 351 

of Table class, 277 
allItems method 

of Array class, 220 

of Collection class, 210 

of Directory class, 239 

of IdentityTable class, 281 

of List class, 247 

of Queue class, 258 

of Relation class, 264 

of Stem class, 273 

of Supplier class, 351 

of Table class, 277 
append method 

of Array class, 220 

of List class, 247 

of MutableBuffer class, 330 

of OrderedCollection class, 214 

of Queue class, 258 
аррепа АП method 

of OrderedCollection class, 214 
args method 

of RexxContext class, 355 
arguments method 

of Message class, 180 
arithmetic methods 

of DateTime class, 296 

of String class, 133 
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of TimeSpan class, 311 
arrayIn method 

of InputStream class, 185 

of Stream class, 190 
arrayOut method 

of OutputStream class, 186 

of Stream class, 191 
at method 

of Array class, 220 

of Collection class, 210 

of Directory class, 240 

of IdentityTable class, 281 

of List class, 247 

of Queue class, 258 

of Relation class, 264 

of Stem class, 273 

of Table class, 278 
available method 

of StreamSupplier class, 353 

of Supplier class, 351 
b2x method 

of String class, 137 
baseClass method 

of Class class, 124 
baseDate method 

of DateTime class, 301 
bitAnd method 

of String class, 138 
bitOr method 

of String class, 138 
bitXor method 

of String class, 139 
c2d method 

of String class, 139 
c2x method 

of String class, 140 
call method 

of Routine class, 171 
callWith method 

of Routine class, 171 
cancel method 

of Alarm class, 306 
caselessAbbrev method 

of String class, 140 
caselessChangeStr method 

of MutableBuffer class, 330 

of String class, 141 


caselessCompareTo method 
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of String class, 142, 142 
caselessCountStr method 
of MutableBuffer class, 330, 330 
of String class, 142, 142 
caselessEquals method 
of String class, 142, 142 
caselessLastPos method 
of MutableBuffer class, 330, 330 
of String class, 143, 143 
caselessMatch method 
of MutableBuffer class, 331, 331 
of String class, 143, 143 
caselessMatchChar method 
of MutableBuffer class, 331, 331 
of String class, 144, 144 
caselessPos method 
of MutableBuffer class, 331, 331 
of String class, 144, 144 
center method 
of String class, 145 
centre method 
of String class, 145 
changeStr method 
of MutableBuffer class, 332 
of String class, 145 
charIn method 
of InputStream class, 185 
of OutputStream class, 187 
of Stream class, 191 
charOut method 
of InputStream class, 185 
of OutputStream class, 187 
of Stream class, 191 
chars method 
of InputStream class, 185 
of OutputStream class, 187 
of Stream class, 191 
civilTime method 
of DateTime class, 303 
class method 
of Object class, 113 
classes method 
of Package class, 175 
close method 
of InputStream class, 185 
of OutputStream class, 187 
of Stream class, 192 


command method 
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of Stream class, 192 
compare method 
of CaselessColumnComparator class, 
322 
of CaselessComparator class, 319 
of CaselessDescendingComparator 
class, 325 
of ColumnComparator class, 320 
of Comparator class, 318 
of DescendingComparator class, 323 
of InvertingComparator class, 326 
of String class, 141, 146 
compareTo method 
of Comparable class, 316 
of DateTime class, 297 
of String class, 146 
of TimeSpan class, 312 
comparison methods 
of Orderable class, 317 
of String class, 134 
completed method 
of Message class, 180 
concatenation methods 
of Object class, 113 
of String class, 136 
condition method 
of RexxContext class, 355 
copies method 
of String class, 146 
copy method 
of Object class, 114 
countStr method 
of MutableBuffer class, 332 
of String class, 147 
create method 
of RexxQueue class, 347 
creation, 85 
current method 
of Monitor class, 328 
d2c method 
of String class, 147 
d2x method 
of String class, 147 
dataType method 
of String class, 148 
date method 
of DateTime class, 304 
day method 


of DateTime class, 298 
dayMicroseconds method 

of DateTime class, 299 
dayMinutes method 

of DateTime class, 298 
dayName method 

of DateTime class, 302 
days method 

of TimeSpan class, 312 
daySeconds method 

of DateTime class, 298 
daysInMonth method 

of DateTime class, 305 
daysInYear method 

of DateTime class, 305 
decodeBase64 method 

of String class, 150 
defaultName method 

of Class class, 124 

of Object class, 114 
define method 

of Class class, 124 
definedMethods method 

of Package class, 175 
definition, 6 
delete class method 

of RexxQueue class, 347 
delete method 

of Class class, 125 

of MutableBuffer class, 332 

of RexxQueue class, 347 
delstr method 

of MutableBuffer class, 333 

of String class, 150 
delWord method 

of MutableBuffer class, 333 

of String class, 150 
description method 

of Stream class, 198 
destination method 

of Monitor class, 328 
difference method 

of Bag class, 230 

of Collection class, 210 

of OrderedCollection class, 215 

of Relation class, 264 
digits method 

of Package class, 175 
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of RexxContext class, 356 
dimension method 

of Array class, 221 
duration method 

of TimeSpan class, 312 
elapsed method 

of DateTime class, 304 
empty method 

of Array class, 221 

of Directory class, 240 

of IdentityTable class, 282 

of List class, 247 

of Queue class, 258 

of Relation class, 264 

of RexxQueue class, 347 

of Stem class, 274 

of Table class, 278 
encodeBase64 method 

of String class, 151 
enhanced method 

of Class class, 125 
entry method 

of Directory class, 240 
equals method 

of String class, 151 
errorCondition method 

of Message class, 180 
europeanDate method 

of DateTime class, 301 
executable method 

of RexxContext class, 356 
exists method 

of RexxQueue class, 347 
findClass method 

of Package class, 175 
findRoutine method 

of Package class, 176 
first method 

of Array class, 221 

of List class, 248 

of Queue class, 258 
firstItem method 

of List class, 248 
flush method 

of Stream class, 198 
form method 

of Package class, 176 

of RexxContext class, 356 
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format method 

of String class, 151 
fromBaseDate method 

of DateTime class, 295 
fromCivilTime method 

of DateTime class, 294 

of TimeSpan class, 310 
fromDays method 

of TimeSpan class, 309 
fromEuropeanDate method 

of DateTime class, 293 
fromHours method 

of TimeSpan class, 309 
fromIsoDate method 

of DateTime class, 295 
fromLongTime method 

of DateTime class, 294 

of TimeSpan class, 310 
fromMicroseconds method 

of TimeSpan class, 309 
fromMinutes method 

of TimeSpan class, 309 
fromNormalDate method 

of DateTime class, 292 
fromNormalTime method 

of DateTime class, 294 

of TimeSpan class, 310 
fromOrderedDate method 

of DateTime class, 293 


fromSeconds method 





of TimeSpan class, 309 
fromStandardDate method 

of DateTime class, 293 
fromStringFormat method 

of TimeSpan class, 310 
fromTicks method 

of DateTime class, 295 
fromUsaDate method 

of DateTime class, 294 
fromUTCIsoDate method 

of DateTime class, 295 
fullDate method 

of DateTime class, 303 
fuzz method 

of Package class, 176 

of RexxContext class, 356 
get method 

of RexxQueue class, 347 
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getBufferSizemethod 

of MutableBuffer class, 333 
getLogical method 

of Properties class, 253 
getProperty method 

of Properties class, 254 
getWhole method 

of Properties class, 254 
hasEntry method 

of Directory class, 240 
hasError method 

of Message class, 181 
hashCode method 

of DateTime class, 299 

of Object class, 114 

of String class, 152 

of TimeSpan class, 313 
hasIndex method 

of Array class, 222 

of Bag class, 230 

of Collection class, 210 

of Directory class, 240 

of IdentityTable class, 282 

of List class, 248 

of Queue class, 258 

of Relation class, 264 

of Stem class, 274 

of Table class, 278 
hasItem method 

of Array class, 222 

of Collection class, 210 

of Directory class, 240 

of IdentityTable class, 282 

of List class, 248 

of Queue class, 258 

of Relation class, 265 

of Stem class, 274 

of Table class, 278 
hasMethod method 

of Object class, 115 
hours method 

of DateTime class, 298 

of TimeSpan class, 312 
id method 

of Class class, 126 
identityHash method 

of Object class, 115 


importedClasses method 


of Package class, 176 
importedRoutines method 

of Package class, 176 
index method 

of Array class, 222 

of Collection class, 211 

of Directory class, 241 

of IdentityTable class, 282 

of List class, 248 

of Queue class, 259 

of Relation class, 265 

of Stem class, 274 

of StreamSupplier class, 354 

of Supplier class, 351 

of Table class, 278 
inherit method 

of Class class, 126 
init method 

of Alarm class, 306 

of CaselessColumnComparator class, 

322 

of CircularQueue class, 233 

of ColumnComparator class, 321 

of DateTime class, 296 

of InvertingComparator class, 327 

of Monitor class, 328 

of Object class, 115 

of RegularExpression class, 342 

of RexxQueue class, 348 

of Stream class, 198 

of StreamSupplier class, 354 

of Supplier class, 351 

of TimeSpan class, 310 
insert method 

of List class, 248 

of MutableBuffer class, 333 

of Queue class, 259 

of String class, 152 
instanceMethod method 

of Object class, 115 
instanceMethods method 

of Object class, 115 
intersection method 

of Bag class, 231 

of Collection class, 211 

of OrderedCollection class, 215 

of Relation class, 265 

of Set class, 269 
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isA method 

of Object class, 116 
isEmpty method 

of Array class, 223 

of Directory class, 241 

of IdentityTable class, 282 

of List class, 249 

of Queue class, 259 

of Relation class, 265 

of Stem class, 274 

of Table class, 278 
isGuarded method 

of Method class, 168 
isInstanceOf method 

of Object class, 116 
isLeapyear method 

of DateTime class, 305 
isNull method 

of Pointer class, 359 
isoDate method 

of DateTime class, 300 
isPrivate method 

of Method class, 168 
isProtected method 

of Method class, 168 
isSubclassOf method 

of Class class, 126 
item method 

of StreamSupplier class, 354 

of Supplier class, 351 
items method 

of Array class, 223 

of Collection class, 211 

of Directory class, 241 

of IdentityTable class, 282 

of List class, 249 

of Queue class, 260 

of Relation class, 265 

of Stem class, 274 

of Table class, 279 
languageDate method 

of DateTime class, 301 
last method 

of Array class, 223 

of List class, 249 

of Queue class, 260 
lastItem method 

of List class, 250 
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lastPos method 
of MutableBuffer class, 334 
of String class, 153 
left method 
of String class, 153 
length method 
of MutableBuffer class, 334 
of String class, 154 
line method 
of RexxContext class, 356 
lineIn method 
of InputStream class, 185 
of OutputStream class, 187 
of RexxQueue class, 348 
of Stream class, 198 
lineOut method 
of InputStream class, 185 
of OutputStream class, 187 
of RexxQueue class, 348 
of Stream class, 199 
lines method 
of InputStream class, 185 
of OutputStream class, 187 
of Stream class, 199 
load method 
of Properties class, 253, 254 
loadExternalMethod method 
of Method class, 167 
loadExternalRoutine method 
of Routine class, 171 
loadLibrary method 
of Package class, 176 
loadPackage method 
of Package class, 177 
logical methods 
of String class, 135 
longTime method 
of DateTime class, 303 
lower method 
of MutableBuffer class, 334 
of String class, 154 
makeArray method 
of Array class, 223 
of CircularQueue class, 234 
of Collection class, 211 
of Directory class, 241 
of IdentityTable class, 283 
of List class, 250 
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of MapCollection class, 214 

of MutableBuffer class, 334 

of Queue class, 260 

of Relation class, 265 

of RexxQueue class, 348 

of Stem class, 274 

of Stream class, 199 

of String class, 154 

of Table class, 279 
makeString method 

of Array class, 224 

of String class, 155 
match method 

of MutableBuffer class, 335 


of RegularExpression class, 342 


of String class, 155 
matchChar method 

of MutableBuffer class, 335 

of String class, 155 
max method 

of String class, 156 
maxDate method 

of DateTime class, 292 
messageName method 

of Message class, 181 
metaClass method 

of Class class, 127 
method method 

of Class class, 127 
methods method 

of Class class, 127 
microseconds method 

of DateTime class, 298 

of TimeSpan class, 313 
min method 

of String class, 156 
minDate method 

of DateTime class, 292 
minutes method 

of DateTime class, 298 

of TimeSpan class, 312 
mixinClass method 

of Class class, 128 
month method 

of DateTime class, 297 
monthName method 

of DateTime class, 302 


name method 


of Package class, 177 


new method 


of Array class, 218 

of Buffer class, 360 

of Class class, 128 

of Directory class, 239 

of IdentityTable class, 281 
of List class, 246 

of Message class, 179 

of Method class, 167 

of MutableBuffer class, 330 
of Object class, 112 

of Package class, 174 

of Pointer class, 359 

of Properties class, 253 

of Queue class, 257 

of Relation class, 263 

of Routine class, 170 

of Stem class, 272 

of Stream class, 190 

of String class, 133 

of Supplier class, 350 

of Table class, 277 

of WeakReference class, 358 


newFile method 


of Method class, 167 
of Package class, 174 


of Routine class, 171 


next method 


of Array class, 224 

of List class, 250 

of Queue class, 260 

of StreamSupplier class, 354 
of Supplier class, 352 


normalDate method 


of DateTime class, 302 


normalTime method 


of DateTime class, 303 


notify method 


of Message class, 181 


objectName method 


of Object class, 116 


objectName= method 


of Object class, 116 


of method 


of Array class, 219 
of Bag class, 230 


of CircularQueue class, 233 
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of List class, 246 
of Queue class, 257 
of Set class, 269 
offset method 
of DateTime class, 304 
open method 
of InputStream class, 185 
of OutputStream class, 187 
of RexxQueue class, 347 
of Stream class, 200 
orderedDate method 
of DateTime class, 302 
overlay method 
of MutableBuffer class, 335 
of String class, 156 
package method 
of Method class, 168 
of RexxContext class, 356 
of Routine class, 172 
parse method 
of RegularExpression class, 342 
peek method 
of Queue class, 260 
pos method 
of MutableBuffer class, 335 
of RegularExpression class, 345 
of String class, 157 
position method 
of InputStream class, 185 
of OutputStream class, 187 
of RegularExpression class, 345 
of Stream class, 201 
prefix +, ??, 22, 2? 
prefix -, ??, ??, ?? 
previous method 
of Array class, 224 
of List class, 250 
of Queue class, 260 
private, 101 
public, 101 
publicClasses method 
of Package class, 177 
publicRoutines method 
of Package class, 177 
pull method 
of Queue class, 260 
of RexxQueue class, 348 
push method 
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of CircularQueue class, 234 

of Queue class, 261 

of RexxQueue class, 348 
put method 

of Array class, 224 

of Bag class, 231 

of Collection class, 211 

of Directory class, 241 

of IdentityTable class, 283 

of List class, 250 

of Properties class, 254 

of Queue class, 261 

of Relation class, 266 

of Set class, 270 

of Stem class, 275 

of Table class, 279 
putAll method 

of Bag class, 231 

of MapCollection class, 213 

of Set class, 270 
qualify method 

of Stream class, 202 
query 

of Stream class, 202 
queryMixinClass method 

of Class class, 129 
queue method 

of CircularQueue class, 234 

of Queue class, 261 

of RexxQueue class, 349 
queued method 

of RexxQueue class, 349 
remove method 

of Array class, 225 

of Directory class, 241 

of IdentityTable class, 283 

of List class, 250 

of Queue class, 261 

of Relation class, 266 

of Stem class, 275 

of Table class, 279 
removeltem method 

of Array class, 225 

of Directory class, 242 

of IdentityTable class, 283 

of List class, 251 

of Queue class, 261 

of Relation class, 266 
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of Stem class, 275 

of Table class, 279 
replaceAt method 

of MutableBuffer class, 336 

of String class, 157 
request method 

of Object class, 117 

of Stem class, 275 
resize method 

of CircularQueue class, 235 
result method 

of Message class, 182 
reverse method 

of String class, 157 
right method 

of String class, 158 
routines method 

of Package class, 177 
rs method 

of RexxContext class, 356 
run method 

of Object class, 117 
save method 

of Properties class, 254 
say method 

of RexxQueue class, 349 

of Stream class, 204 
scope, 99 
search order 

changing, 100 
seconds method 

of DateTime class, 298 

of TimeSpan class, 312 
section method 

of Array class, 226 

of List class, 251 
seek method 

of Stream class, 204 
selection 

search order, 100 
send method 

of Message class, 182 

of Object class, 118 
sendWith method 

of Object class, 119 
set method 

of RexxQueue class, 349 
setBufferSizemethod 


of MutableBuffer class, 336 
setEntry method 

of Directory class, 242 
setGuarded method 

of Method class, 168 
setLogical method 

of Properties class, 255 
setMethod method 

of Directory class, 242 

of Object class, 119 
setPrivate method 

of Method class, 168 
setProperty method 

of Properties class, 255 
setProtected method 

of Method class, 169 
setSecurityManager method 

of Method class, 169 

of Package class, 177 

of Routine class, 172 
setUnguarded method 

of Method class, 169 
setWhole method 

of Properties class, 255 
sign method 

of String class, 158 

of TimeSpan class, 315 
size method 

of Array class, 226 

of CircularQueue class, 235 
sort method 

of Array class, 226 
sortWith method 

of Array class, 226 
source method 

of Method class, 169 

of Package class, 178 

of Routine class, 172 
sourceLine method 

of Package class, 178 
sourceSize method 

of Package class, 178 
space method 

of String class, 158 
stableSort method 

of Array class, 227 
stableSortWith method 

of Array class, 227 
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standardDate method 
of DateTime class, 302 
start method 
of Message class, 182 
of Object class, 120 
startWith method 
of Object class, 120 
state method 
of Stream class, 205 
string method 
of CircularQueue class, 235 
of DateTime class, 305 
of MutableBuffer class, 336 
of Object class, 121 
of Stream class, 206 
of TimeSpan class, 315 
strip method 
of String class, 159 
subchar method 
of MutableBuffer class, 336 
of String, 159 
subclass method 
of Class class, 129 
subclasses method 
of Class class, 130 
subset method 
of Bag class, 231 
of Collection class, 211 
of OrderedCollection class, 215 
of Relation class, 266 
of Set class, 270 
substr method 
of MutableBuffer class, 337 
of String class, 159 
subWord method 
of MutableBuffer class, 337 
of String class, 160 
superClass method 
of Class class, 130 
superClasses method 
of Class class, 130 
supplier method 
of Array class, 227 
of CircularQueue class, 236 
of Collection class, 212 
of Directory class, 242 
of IdentityTable class, 283 
of List class, 251 
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of Queue class, 261 

of Relation class, 266 

of Stem class, 275 

of Stream class, 206 

of Supplier class, 352 

of Table class, 279 
target method 

of Message class, 183 
ticks method 

of DateTime class, 304 
timeOfDay method 

of DateTime class, 304 
today method 

of DateTime class, 292 
toDirectory method 

of Stem class, 275 
toString method 

of Array class, 227 
totalDays method 

of TimeSpan class, 313 
totalHours method 

of TimeSpan class, 313 
totalMicroseconds method 

of TimeSpan class, 313 
totalMinutes method 

of TimeSpan class, 313 
totalSeconds method 

of TimeSpan class, 313 
toTimeZone method 

of DateTime class, 304 
trace method 

of Package class, 178 
translate method 

of MutableBuffer class, 337 

of String class, 160 
trunc method 

of String class, 161 
uninherit method 

of Class class, 130 
uninit method 

of Stream class, 206 
union method 

of Bag class, 231 

of Collection class, 212 

of OrderedCollection class, 215 

of Relation class, 266 

of Set class, 270 
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of Directory class, 242 

of Monitor class, 328 

of Stem class, 276 
unsetMethod method 

of Directory class, 243 

of Object class, 122 
upper method 

of MutableBuffer class, 337 

of String class, 162 
usaDate method 

of DateTime class, 303 
utcDate method 

of DateTime class, 303 
utcIsoDate method 

of DateTime class, 300 
value method 

of WeakReference class, 358 
variables method 

of RexxContext class, 357 
verify method 

of MutableBuffer class, 338 

of String class, 162 
weekDay method 

of DateTime class, 301 
word method 

of MutableBuffer class, 339 

of String class, 163 
wordIndex method 

of MutableBuffer class, 339 

of String class, 163 
wordLength method 

of MutableBuffer class, 339 

of String class, 163 
wordPos method 

of MutableBuffer class, 332, 339 

of String class, 144, 163 
words method 

of MutableBuffer class, 339 

of String class, 164 
x2b method 

of String class, 164 
x2c method 

of String class, 165 
x2d method 

of String class, 165 
xor method 

of Bag class, 231 

of Collection class, 212 


of Directory class, 243 
of OrderedCollection class, 215 
of Relation class, 267 
of Set class, 270 
year method 
of DateTime class, 297 
yearDay method 
of DateTime class, 301 
[] method 
of Array class, 219 
of Collection class, 209 
of Directory class, 239 
of IdentityTable class, 281 
of List class, 247 
of Queue class, 257 
of Relation class, 263 
of Stem class, 272 
of Table class, 277 
Пе method 
of Array class, 219 
of Bag class, 230 
of Collection class, 209 
of Directory class, 239 
of IdentityTable class, 281 
of List class, 247 
of Properties class, 253 
of Queue class, 257 
of Relation class, 263 
of Set class, 269 
of Stem class, 273 
of Table class, 277 
Қ? 
ұ>,22,9? 
\>>, ??,?? 
\<, 22,2? 
иа аа 
\= 
of Object class, 113 
of Orderable class, ?? 
of Pointer class, ?? 
of String class, ?? 
of Object class, 113 
of Orderable class, ?? 
of Pointer class, ?? 
of String class, ?? 
|, 2? 
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Method class, 166 
method method 

of Class class, 127 
methods method 

of Class class, 127 
microseconds method 

of DateTime class, 298 

of TimeSpan class, 313 
MIN function 

description, 404 

example, 404 
min method 

of String class, 156 
minDate method 

of DateTime class, 292 
minutes calculated from midnight, 421 
minutes method 

of DateTime class, 298 

of TimeSpan class, 312 
mixin classes, 94 
mixinClass method 

of Class class, 128 
MIXINCLASS subkeyword 

in a CLASS directive, 83 
model of input and output, 557 
modularizing data, 2 
monitor, 549 
Monitor class, 327 
month method 

of DateTime class, 297 
Month option of DATE function, 392 
monthName method 

of DateTime class, 302 
multiple inheritance, 8 
multiplication operator, ?? 
MutableBuffer class, 328 


name method 
of Package class, 177 
NAME subkeyword 
in a CALL instruction, 42 
in a SIGNAL instruction, 72 
name, definition, 39 
names 
of functions, 367 
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of programs, 61 

of subroutines, 42 

of variables, 14 
negation 

of logical values, ?? 
new method 

of Array class, 218 

of Buffer class, 360 

of Class class, 128 

of Directory class, 239 

of IdentityTable class, 281 

of List class, 246 

of Message class, 179 

of Method class, 167 

of MutableBuffer class, 330 

of Object class, 112 

of Package class, 174 

of Pointer class, 359 

of Properties class, 253 

of Queue class, 257 

of Relation class, 263 

of Routine class, 170 

of Stem class, 272 

of Stream class, 190 

of String class, 133 

of Supplier class, 350 

of Table class, 277 

of WeakReference class, 358 
newFile method 

of Method class, 167 

of Package class, 174 

of Routine class, 171 
next method 

of Array class, 224 

of List class, 250 

of Queue class, 260 

of StreamSupplier class, 354 

of Supplier class, 352 
nibbles, 13 
NOMETHOD subkeyword 

in a SIGNAL instruction, 72, 528, 532 
NOP instruction 

description, 57 

example, 58 
Normal option of DATE function, ?? 
normalDate method 

of DateTime class, 302 


normalTime method 
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of DateTime class, 303 
NOSTRING subkeyword 
in a SIGNAL instruction, 72, 528, 532 
not equal operator, ?? 
not greater than operator, ?? 
not less than operator, ?? 
NOT operator, 16, ?? 
notation 
engineering, 522 
exponential, example, 522 
scientific, 522 
Notices, 643 
notify method 
of Message class, 181 
NOTREADY condition 
condition trapping, 565 
reaised by stream errors, 565 
NOTREADY subkeyword 
in a CALL instruction, 42, 532 
in a SIGNAL instruction, 72, 528, 532 
NOVALUE condition 
not raised by VALUE function, 428 
use of, 571 
NOVALUE subkeyword 
in a SIGNAL instruction, 72, 528, 532 
null 
clauses, 26 
strings, 12 
numbers 
arithmetic on, 20, 519, 520 
checking with dataType, 148, 389 
comparison of, 20, 523 
description, 15, 519 
formatting for display, 151, 397 
implementation maximum, 15 
in DO instruction, 45 
in LOOP instruction, 57 
truncating, 161, 425 
use in the language, 524 
numbers for display, 151, 397 
numeric 
comparisons, example, 524 
options in TRACE, 76 
NUMERIC instruction 
description, 58, 58 
DIGITS option, 58 
FORM option, 58, 523 
FUZZ option, 59 


settings saved during subroutine calls, 44 


object, 17 
as data value, 18 
definition, 4 
kinds of, 4 
Object class, 111 
object classes, 8, 93 
object method, 93 
object variable pool, 48, 540 
object-based concurrency, 537 
object-oriented programming, 1 
objectName method 
of Object class, 116 
objectName= method 
of Object class, 116 
of method 
of Array class, 219 
of Bag class, 230 
of CircularQueue class, 233 
of List class, 246 
of Queue class, 257 
of Set class, 269 
OFF subkeyword 
in a CALL instruction, 42 
in a SIGNAL instruction, 72 
in an GUARD instruction, 51 
offset method 
of DateTime class, 304 
ON subkey word 
in a CALL instruction, 42 
in a SIGNAL instruction, 72 
in an GUARD instruction, 51 
ooRexx License, 645 
open method 
of InputStream class, 185 
of OutputStream class, 187 
of RexxQueue class, 347 
of Stream class, 200 
Open Object Rexx License, 645 
operations 
tracing results, 73 
operator 
arithmetic 
description, 18, 519, 520 
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list, 20 

as message, 18 

as special characters, 15 

characters, 15 

comparison, 20, 523 

concatenation, 19 

examples, 522 

logical, 21 

precedence (priorities) of, 21 
options 

alphabetical character word options, 74 

numeric in TRACE, 76 
OPTIONS instruction 

description, 59 
OR, logical, ?? 
Orderable class, 316 
Ordered collection classes 

Array class, 216 

CircularQueue class, 232 

List class, 244 

Queue class, 255 
Ordered option of DATE function, 392 
OrderedCollection class, 214 
orderedDate method 

of DateTime class, 302 
ORing character together, 138, 380 
OTHERWISE 

as free standing clause, 39 
OTHERWISE subkeyword 

in a SELECT instruction, 70 
output 

errors during, 565 

object, 365 

to the user, 557 
OutputStream class, 186 
OVER subkeyword 

in a DO instruction, 45, 585 

ina LOOP instruction, 56, 585 
overflow, arithmetic, 525 
OVERLAY function 

description, 405 

example, 405 
overlay method 

of MutableBuffer class, 335 

of String class, 156 
overlaying a string onto another, 156, 405 


overview of parsing, 515 
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Package class, 172 
package method 
of Method class, 168 
of RexxContextclass, 356 
of Routine class, 172 
packing a string with X2C, 165, 431 
pad character, definition, 375 
page, code, 10 
parentheses 
adjacent to whitespace, 16 
in expressions, 21 
in function calls, 367 
in parsing templates, 509 
PARSE instruction 
description, 59 
example, 61 
PARSE LINEIN method 
role in input and output, 558 
parse method 
of RegularExpression class, 342 
PARSE PULL method 
role in input and output, 558 
parsing, 506, 507 
advanced topics, 512 
combining patterns and parsing into words 
string, 508 
combining string and positional patterns, 
513 
conceptual overview, 514 
description, 501, 515 
equal sign, 506 
examples 
combining positional patterns with 
parsing into words, 509 
combining string and positional patterns, 
513 
combining string pattern and parsing 
into words, 508 
parsing instructions, 511 
parsing multiple strings in a subroutine, 
513 
period as a placeholder, 503 
simple template, 501 
templates containing positional patterns, 
505 


templates containing string patterns, 504 
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using a variable as a string pattern, 510 
using an expression as a positional 
pattern, 510 
into words, 501 
patterns 
positional, 501, 505 
string, 501, 503 
word parsing, conceptual overview, 517 
period as placeholder, 503 
positional patterns, 501 
absolute, 505 
variable, 510 
selecting words, 501 
several assignments, 509 
several strings, 512 
source string, 501 
special case, 513 
steps, 515 
string patterns, 501 
literal string patterns, 503 
variable string patterns, 509 
summary of instructions, 511 
templates 
in ARG instruction, 41 
in PARSE instruction, 60 
in PULL instruction, 64 
treatment of blanks, 502 
treatment of whitespace, 502 
UPPER, use of, 510 
variable patterns 
string, 510 
word parsing 
conceptual overview, 517 


description and examples, 501 


patterns in parsing 


combined with parsing into words, 508 
conceptual overview, 515, 516, 517 
positional, 501, 505 

string, 501, 503 


peek method 


of Queue class, 260 


period 


as placeholder in parsing, 503 
causing substitution in variable names, 32 


in numbers, 519 


permanent command destination change, 39 
persistent input and output, 557 


Pointer class, 358 


polymorphism, 6 
POS function 
description, 405 
example, 405 
pos method 
of MutableBuffer class, 335 
of RegularExpression class, 345 
of String class, 157 
position 
last occurrence of a string, 153, 334, 399 
position method 
of InputStream class, 185 
of OutputStream class, 187 
of RegularExpression class, 345 
of Stream class, 201 
positional patterns 
absolute, 503 
description, 501 
length, 507 
relative, 506 
variable, 510 
power operator, ?? 
powers of ten in numbers, 15 
precedence of operators, 21 
prefix + method, 136 
prefix + operator, ?? 
prefix - method, 136 
prefix - operator, ?? 
prefix \ operator, 20, 21 
presumed command destinations, 39 
previous method 
of Array class, 224 
of List class, 250 
of Queue class, 260 
private method, 101 
PRIVATE subkeyword 
іп a CLASS directive, 83 
in a METHOD directive, 85 
in a ROUTINE directive, 91 
in an ATTRIBUTE directive, 81 
PROCEDURE instruction 
description, 62 
example, 63 
programming restrictions, 1 
programs 
arguments to, 41 
examples, 564 
retrieving lines with SOURCELINE, 410 
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retrieving name of, 61 
programs without source, 581 
PROPAGATE subkeyword 

in a RAISE instruction, 66 
Properties class, 251 
PROTECTED subkeyword 

in a METHOD directive, 85 

in an ATTRIBUTE directive, 81 
protecting variables, 62 
pseudo random number RANDOM function, 
406 
public method, 101 
public object 

.CONTEXT object, 366 

.ENDOFLINE object, 363 

.ERROR object, 364 

.FALSE object, 363 

.INPUT object, 365 

.LINE object, 366 

.LOCAL object, 364 

. METHOD object, 366 

.Nil object, 363 

.OUTPUT object, 365 

.RS object, 366 

.STDERR object, 365 

.STDIN object, 365 

.STDOUT object, 365 

.STDQUE object, 365 

.TRUE object, 363 
PUBLIC subkeyword 

in a CLASS directive, 83 

in a METHOD directive, 85 

in a ROUTINE directive, 91 

in an ATTRIBUTE directive, 81 
publicClasses method 

of Package class, 177 
publicRoutines method 

of Package class, 177 
PULL instruction 

description, 64 

example, 65 
pull method 

of Queue class, 260 

of RexxQueue class, 348 

role in input and output, 558 
PULL option of PARSE instruction, 61 
PULL subkeyword 

in a PARSE instruction, 59, 511 
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in an PARSE instruction, 64 QUEUE instruction 


PUSH instruction description, 65 
description, 65 example, 66 
example, 65 role in input and output, 559 
push method Queue interface from Rexx programs, 408 
of CircularQueue class, 234 queue method 
of Queue class, 261 of CircularQueue class, 234 
of RexxQueue class, 348 of Queue class, 261 
put method of RexxQueue class, 349 
of Array class, 224 QUEUED function 
of Bag class, 231 description, 406 
of Collection class, 211 example, 406 
of Directory class, 241 role in input and output, 560 
of IdentityTable class, 283 queued method 
of List class, 250 of RexxQueue class, 349 


of Properties class, 254 
of Queue class, 261 


of Relation class, 266 R 
of Set class, 270 
of Stem class, 275 RAISE instruction 
of Table class, 279 description, 66 
putAll method example, 67 
of Bag class, 231 RANDOM function 
of MapCollection class, 213 description, 406 
of Set class, 270, 270 example, 406 
random number RANDOM function, 406 
RC (return code) 
Q not set during interactive debug, 567 
set by commands, 36 
QUALIFY function special variable, ??, 573 
description, 406 RC special variable 
qualify method description, 573 
of Stream class, 202 read position in a stream, 558 
query external function, 408 recursive call, 44, 368 
QUERY keyword register external functions, 407 
ina RXSUBCOM command, 578 REGISTER keyword 
query method in a RXSUBCOM command, 576 
of Stream class, 202 RegularExpression class, 339 
queryMixinClass method Relation class, 262 
of Class class, 129 relative positional pattern 
queue positional patterns 
creating and deleting queues, 408 relative, 506 
named, 559 remainder 
naming and querying, 408 description>, 521 
RXQUEUE function, 408 remainder operator, ?? 
session, 559 remove method 
unnamed, 559 of Array class, 225 
Queue class, 255 of Directory class, 241 
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of IdentityTable class, 283 
of List class, 250 
of Queue class, 261 
of Relation class, 266 
of Stem class, 275 
of Table class, 279 
removeltem method 
of Array class, 225 
of Directory class, 242 
of IdentityTable class, 283 
of List class, 251 
of Queue class, 261 
of Relation class, 266 
of Stem class, 275 
of Table class, 279 
reordering data, 160, 337, 424 
repeating s string with copies, 146, 387 
repetitive loops 
altering flow, 55 
controlled repetitive loops, 584 
exiting, 55 
simple DO group, 583 
replaceAt method 
of MutableBuffer class, 336 
of String class, 157 
replacing characters within a string, 157, 336 
REPLY instruction 
description, 68 
example, 68 
request method 
of Object class, 117 
of Stem class, 275 
reservation of keywords, 571 
resize method 
of CircularQueue class, 235 
restrictions 
embedded in numbers, 15 
first character of variable name, 28 
in programming, | 
result method 
of Message class, 182 
RESULT special variable 
description, 573 
return value from a routine, 374 
set by RETURN instruction, 44, 69 
retrieving 
argument strings with ARG, 41 
arguments with ARG function, 377 


690 


lines with SOURCELINE, 410 
return 
code 
as set by commands, 36 
setting on exit, 47 
string 
setting on exit, 47 
RETURN instruction 
description, 69 
RETURN subkeyword 
in a RAISE instruction, 66 
returning control from Rexx program, 69 
REVERSE function 
description, 407 
example, 407 
reverse method 
of String class, 157 
RexxContext class, 354 
RexxQueue class, 345 
rexxutil functions, 435 
RxMessageBox, 438 
example, 440 
RxWinExec, 440 
SysAddRexxMacro, 442 
SysBootDrive, 442 
SysClearRexxMacroSpace, 443 
SysCloseEventSem, 443 
SysCloseMutexSem, 443 
SysCls, 444 
SysCreateEventSem, 444 
SysCreateMutexSem, 445 
SysCreatePipe, 445 
SysCurPos, 445 
example, 446 
SysCurState, 446 
SysDriveInfo, 446 
example, 447 
SysDriveMap, 447 
example, 448 
SysDropFuncs, 448 
SysDropRexxMacro, 448 
SysDumpVariables, 448 
example, 449 
SysFileCopy, 449 
example, 449 
SysFileDelete, 450 
example, 450 
SysFileExists, 451 
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SysFileMove, 451 SysSearchPath, 480 


example, 452 example, 480 
SysFileSearch, 452 SysSetFileDateTime, 481 
example, 453 example, 481 
SysFileSystemType, 454 SysSetPriority, 481 
example, 454 SysShutdownSystem, 482 
SysFileTree, 454 SysSleep, 483 
example, 457 example, 483 
SysFork, 457 SysStemCopy, 484 
SysFromUnicode, 459 example, 485 
SysGetErrortext, 461 SysStemDelete, 485 
example, 461 example, 485 
SysGetFileDateTime, 461 SysStemInsert, 486 
example, 462 SysStemSort, 486 
SysGetKey, 462 example, 487 
SysGetMessage, 462 SysSwitchSession, 488 
example, 463 SysSystemDirectory, 488 
SysGetMessageX, 463 SysTempFileName, 488 
example, 464 example, 489 
SysIni, 464 SysTextScreenRead, 490 
example, 466 example, 490 
SysIsFile, 466 SysTextScreenSize, 490 
SysIsFileCompressed, 467 example, 490 
SysIsFileDirectory, 467 SysToUnicode, 491 
SysIsFileEncrypted, 468 SysUtilVersion, 493 
SysIsFileLink, 468 SysVersion, 493 
SysIsFileNotContentIndexed, 469 SysVolumeLabel, 494 
SysIsFileOffline, 469 SysWait, 494 
SysIsFileSparse, 470 SysWaitEventSem, 494 
SysIsFileTemporary, 470 SysWaitNamedPipe, 495 
SysLinVer, 471 SysWinDecryptFile, 496 
SysLoadFuncs, 471 SysWinEncryptFile, 496 
SysLoadRexxMacroSpace, 471 SysWinGetDefaultPrinter, 497 
SysMkDir, 472 example, 498 
example, 473 SysWinGetPrinters, 497 
SysOpenEventSem, 473 example, 498 
SysOpenMutexSem, 473 SysWinSetDefaultPrinter, 498 
SysPostEventSem, 473 example, 498 
SysPulseEventSem, 474 SysWinVer, 499 
SysQueryProcess, 474 RIGHT function 
SysQueryRexxMacro, 476 description, 407 
SysReleaseMutexSem, 476 example, 407 
SysReorderRexxMacro, 477 right method 
SysRequestMutexSem, 477 of String class, 158 
SysResetEventSem, 478 rounding 
SysRmDir, 478 using a character string as a number, 15 
example, 479 Routine class, 169 
SysSaveRexxMacroSpace, 480 routines method 
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of Package class, 177 
rs method 

of RexxContextclass, 356 
run method 

of Object class, 117 
running off the end of a program, 69 
RXFUNCADD function 

description, 407 

example, 408 
RXFUNCDROP function 

description, 408 

example, 408 
RXFUNCQUERY function 

description, 408 

example, 408 
RXFUNCQUEUE function 

example, 409 
RxMessageBox, 438 

example, 440 
RXQUEUE filter, 579 
RXQUEUE function 

description, 408 
RXSUBCOM command, 576 
RXTRACE environment variable, 568 
RxWinExec, 440 


save method 
of Properties class, 254 
SAY instruction 
description, 69 
displaying data, 69 
example, 70 
role in output, 558 
say method 
of RexxQueue class, 349 
of Stream class, 204 
scientific notation, 522 
SCIENTIFIC subkeyword 
in a NUMERIC instruction, 58 
scope 
alternating exclusive access, 544 
description, 99 
search order 
external functions, 368 


for functions, 368 
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for methods 
changing, 100 
default, 100 

for subroutines, 43 
seconds calculated from midnight, 422 
seconds method 

of DateTime class, 298 

of TimeSpan class, 312 
section method 

of Array class, 226 

of List class, 251 
Security Manager, 551 

calls to, 551 
seek method 

of Stream class, 204 
SELECT instruction 

description, 70 

example, 71 
selecting a default with ABBREV function, 
375 
selecting a default with abbrev method, 136 
selecting a default with caselessAbbrev 
method, 140 
SELF special variable 

description, 573 
semaphore, 545 
semicolons 

implied, 16 

omission of, 39 

within a clause, 9 
send method 

of Message class, 182 

of Object class, 118 
sendWith method 

of Object class, 119 
sequence, collating using XRANGE, 432 
serial input and output, 557 
Set class, 268 
Set Collection classes 

Bag class, 228 

Set class, 268 
set method 

of RexxQueue class, 349 
SET subkeyword 

in an ATTRIBUTE directive, 81 
set-operator methods, 286 
setBufferSize method 

of MutableBuffer class, 336 
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SetCollection class, 216 
setEntry method 

of Directory class, 242 
setGuarded method 

of Method class, 168 
SETLOCAL function 

description, 410 

example, 410 
setLogical method 

of Properties class, 255 
setMethod method 

of Directory class, 242 

of Object class, 119 
setPrivate method 

of Method class, 168 
setProperty method 

of Properties class, 255 
setProtected method 

of Method class, 169 
setSecurityManager method 

of Method class, 169 

of Package class, 177 

of Routine class, 172 
SETUNGUARDED method, 543 

of Method class, 169 
setWhole method 

of Properties class, 255 
shared library (RexxUtil), 435 
SIGL 

in CALL instruction, 44 

in condition trapping, 533 

in SIGNAL instruction, 73 
SIGL special variable 

description, 573 
SIGN function 

description, 410 

example, 410 
sign method 

of String class, 158 

of TimeSpan class, 315 
SIGNAL instruction 

description, 72 

example, 73 

execution of in subroutines, 45 
significant digits in arithmetic, 520 
simple 

repetitive loops, 583 

symbols, 29 
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size method 

of Array class, 226 

of CircularQueue class, 235 
sort method 

of Array class, 226 
sortWith method 

of Array class, 226 
source 


of program and retrieval of information, 61 


string, 501 

source method 
of Method class, 169 
of Package class, 178 


of Routine class, 172 


SOURCE option of PARSE instruction, 61 


SOURCE subkeyword 
in a PARSE instruction, 59, 511 
sourceless programs, 581 
SOURCELINE function 
description, 410 
example, 411 
sourceLine method 
of Package class, 178 
sourceSize method 
of Package class, 178 
SPACE function 
description, 411 
example, 411 
space method 


of String class, 158 


spacing, formatting, SPACE function, 411 


spacing, formatting, space method, 158 


special 
characters and example, 16 
parsing case, 513 
variable 
RC, 573 
RESULT, 44, 69, 374, 573 
SELF, 573 
SIGL, 44, 573 
SUPER, 573 
variables 
RC, 36, 533, 573 
RESULT, 69, 374, 573 
SELF, 573 
SIGL, 533, 573 
SUPER, 573 
stableSort method 


of Array class, 227 
stableSortWith method 
of Array class, 227 
standard input and output, 561 
Standard option of DATE function, 392 
standardDate method 
of DateTime class, 302 
start method 
of Message class, 182 
of Object class, 120 
startWith method 
of Object class, 120 
State method, 565 
of Stream class, 205 
Stem class, 271 
stem of a variable 
assignment to, 29 
description, 32 
used in DROP instruction, 47 
used in PROCEDURE instruction, 64 
steps in parsing, 514 
stream, 557 
character positioning, 562 
function overview, 563 
line positioning, 562 
Stream class, 189 
stream errors, 565 
STREAM function 
command options, 412 
command strings, 412 
description, 411 
example, 415, 416 
options, 413 
query options, 416 
write options, 413 
StreamSupplier class, 352 
strict comparison, 20, 20 
STRICT subkeyword 
in a USE instruction, 78 
strictly equal operator, 20, ?? 
strictly greater than operator, 20, ?? 
strictly greater than or equal operator, ?? 
strictly less than operator, 20, ?? 
strictly not equal operator, 20, ?? 
strictly not greater than operator, ?? 
strictly not less than operator, ?? 
string 


as literal constant, 12 
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as name of function, 12 
as name of subroutine, 42 
binary specification of, 13 
centering using center function, 145 
centering using CENTER method, 382 
centering using centre function, 145 
centering using CENTRE method, 382 
comparison of, 20 
concatenation of, 19 
copying using copies, 146, 387 
decodeBase64 method, 150 
deleting part, DELSTR function, 394 
deleting part, delStr method, 150 
description, 12 
encodeBase64 method, 151 
extracting using SUBSTR function, 419 
extracting using substr method, 159 
extracting words with SUBWORD, 419 
from stream, 383 
hexidecimal specification of, 13 
interpretation of, 53 
lowercasing using LOWER function, 404 
null, 12 
patterns 
description, 501 
literal, 503 
variable, 509 
quotations marks in, 12 
reapting using COPIES, 387 
repeating using copies, 146 
uppercasing using UPPER function, 425 
verifying contents of, 162, 338, 429 
String class, 131 
string method 
of CircularQueue class, 235 
of daysInMonth class, 305, 315 
of MutableBuffer class, 336 
of Object class, 121 
of Stream class, 206 
STRIP function 
description, 418 
example, 419 
strip method 
of String class, 159 
structure and syntax, 9 
subchar method 
of String class, 159 


subcharmethod 
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of MutableBuffer class, 336 
subclass method 

of Class class, 129 
SUBCLASS subkeyword 

in a CLASS directive, 83 
subclasses, 8 
subclasses method 

of Class class, 130 
subexpression, 18 
subkey word, 27 
subroutines 

calling of, 42 

definition, 367 

forcing built-in or external reference, 42 

naming of, 42 

passing back values from, 69 

return from, 69 

use of labels, 42 

variables in, 62 
subset method 

of Bag class, 231 

of Collection class, 211 

of OrderedCollection class, 215 

of Relation class, 266 
subsidiary list, 46, 48, 62 
substitution 

in variable names, 32 
SUBSTR function 

description, 419 

example, 419 
substr method 

of MutableBuffer class, 337 

of String class, 159 
subtraction operator, ?? 
SUBWORD function 

description, 419 

example, 419 
subWord method 

of MutableBuffer class, 337 

of String class, 160 
summary 

parsing instructions, 511 
SUPER special variable 

description, 573 
superClass method 

of Class class, 130 
superclasses, 8 


superClasses method 
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of Class class, 130 
Supplier class, 349 
supplier method 

of Array class, 227 

of CircularQueue class, 236 

of Collection class, 212 

of Directory class, 242 

of IdentityTable class, 283 

of List class, 251 

of Queue class, 261 

of Relation class, 266 

of Stem class, 275 

of Stream class, 206 

of Supplier class, 352 

of Table class, 279 
symbol 

assigning values to, 28, 28 

classifying, 28 

compound, 32 

constant, 28 

description, 14 

simple, 28 

uppercase translation, 14 

use of, 28, 28 

valid names, 14 
SYMBOL function 

description, 420 

example, 420 
symbols 

environment, 33 
syntax 

error 

traceback after, 78 
trapping with SIGNAL instruction, 527 

general, 9 
SYNTAX subkeyword 

in a RAISE instruction, 66 

in a SIGNAL instruction, 72, 529, 533 
SysAddBootDrive, 442 
SysAddRexxMacro, 442 
SysClearRexxMacroSpace, 443 
SysCloseEventSem, 443 
SysCloseMutexSem, 443 
SysCls, 444 
SysCreateEventSem, 444 
SysCreateMutexSem, 445 
SysCreatePipe, 445 
SysCurPos, 445 


example, 446 
SysCurState, 446 
SysDriveInfo, 446 

example, 447 
SysDriveMap, 447 

example, 448 
SysDropFuncs, 448 
SysDropRexxMacro, 448 
SysDump Variables, 448 

example, 449 
SysFileCopy, 449 

example, 449 
SysFileDelete, 450 

example, 450 
SysFileExists, 451 
SysFileMove, 451 

example, 452 
SysFileSearch, 452 

example, 453 
SysFileSystemType, 454 

example, 454 
SysFileTree, 454 

example, 457 
SysFork, 457 
SysFromUnicode, 459 
SysGetErrortext, 461 

example, 461 
SysGetFileDateTime, 461 

example, 462 
SysGetKey, 462 
SysGetMessage, 462 

example, 463 
SysGetMessageX, 463 

example, 464 
SysIni, 464 

example, 466 
SysIsFile, 466 
SysIsFileCompressed, 467 
SysIsFileDirectory, 467 
SysIsFileEncrypted, 468 
SysIsFileLink, 468 
SysIsFileNotContentIndexed, 469 
SysIsFileOffline, 469 
SysIsFileSparse, 470 
SysIsFileTemporary, 470 
SysLinVer, 471 
SysLoadFuncs, 471 
SysLoadRexxMacroSpace, 471 
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SysMkDir, 472 
example, 473 
SysOpenEventSem, 473 
SysOpenMutexSem, 473 
SysPostEventSem, 473 
SysPulseEventSem, 474 
SysQueryProcess, 474 
SysQueryRexxMacro, 476 
SysReleaseMutexSem, 476 
SysReorderRexxmacro, 477 
SysRequestMutexSem, 477 
SysResetEventSem, 478 
SysRmDir, 478 
example, 479 
SysSaveRexxMacroSpace, 480 
SysSearchPath, 480 
example, 480 
SysSetFileDateTime, 481 
example, 481 
SysSetPriority, 481 
SysShutdownSystem, 482 
SysSleep, 483 
example, 483 
SysStemCopy, 484 
example, 485 
SysStemDelete, 485 
example, 485 
SysStemInsert, 486 
SysStemSort, 486 
example, 487 
SysSwitchSession, 488 
SysSystemDirectory, 488 
SysTempFileName, 488 
example, 489 
SysTextScreenRead, 490 
example, 490 
SysTextScreenSize, 490 
example, 490 
SysToUnicode, 491 
SysUtilVersion, 493 
SysVersion, 493 
SysVolumeLabel, 494 
SysWait, 494 
SysWaitEventSem, 494 
SysWaitNamedPipe, 495 
SysWinDecryptFile, 496 
SysWinEncryptFile, 496 
SysWinGetDefaultPrinter, 497 
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example, 498 
SysWinGetPrinters, 497 
example, 498 
SysWinSetDefaultPrinter, 498 
example, 498 
SysWinVer, 499 


Table class, 276 
tail, 32 
target method 
of Message class, 183 
template 
definition, 501 
list 
ARG instruction, 41 
PARSE instruction, 59 
PULL instruction, 64 
temporary change of, 39 
temporary command destination change, 39 
ten, powers of, 522 
terminal 
reading from with PULL, 64 
writing to with SAY, 69 
terms and data, 17 
testing, 375, 420 
abbreviations with abbrev method, 136 
abbreviations with caselessAbbrev method, 
140 
THEN 
as free standing clause, 39 
following IF clause, 52 
following WHEN clause, 70 
THEN subkeyword 
in a SELECT instruction, 70 
in an IF instruction, 52 
thread, 459, 474, 474, 491, 537 
ticks method 
of DateTime class, 304 
Ticks option of DATE function, 392 
Ticks option of Time function, 422 
tilde (~), 5 
TIME function 
description, 420 
example, 422, 423 


implementation maximum, 423 
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timeOfDay method 

of DateTime class, 304 
TimeSpan class, 307 
tips, tracing, 76 
TO phrase of DO instruction, 46 
TO phrase of LOOP instruction, 57 
TO subkeyword 

in a DO instruction, 45, 584 

in a LOOP instruction, 56, 584 
today method 

of DateTime class, 292 
toDirectory method 

of Stem class, 275 
tokens 

binary strings, 13 

description, 12 

hexadecimal strings, 13 

literal strings, 12 

numbers, 15 

operator characters, 15 

special characters, 16 

symbols, 14 
toString method 

of Array class, 227 
totalDays method 

of TimeSpan class, 313 
totalHours method 

of TimeSpan class, 313 
totalMicroseconds method 

of TimeSpan class, 313 
totalMinutes method 

of TimeSpan class, 313 
totalSeconds method 

of TimeSpan class, 313 
toTimeZone method 

of DateTime class, 304 
TRACE function 

description, 423 

example, 424 
TRACE instruction 

alphabetical character word options, 74 

description, 73 

example, 76 
trace method 

of Package class, 178 
TRACE setting 

altering with TRACE function, 423 

altering with TRACE instruction, 73 


querying, 423 
traceback, on syntax error, 78 
tracing 
action saved during subroutine calls, 44 
by interactive debug, 567 
data identifiers, 77 
execution of programs, 73 
tips, 76 
tracing flag 
>>>,77 
>>, Т? 
>А>,77 
>Е>,77 
>Е>,77 
>L>, 78 
>M>, 78 
>O>, 78 
>P>, 78 
>V>, 78 
ж.ж 77 
+++, 77 
=>>,77 
trailing 
whitespace removed using STRIP function, 
418 
whitespace removed using strip method, 
159 
transient input and output, 557 
TRANSLATE function 
description, 424 
example, 424 
translate method 
of MutableBuffer class, 337 
of String class, 160 
translation 
with TRANSLATE function, 424 
with translate method, 160, 337 
trap conditions 
explanation, 527 
how to, 527 
information about trapped conditions, 385 
using CONDITION function, 385 
trapname, 529 
TRUNC function 
description, 425 
example, 425 
trunc method 


of String class, 161 
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truncating numbers, 161, 425 

twiddle (~), 5 

type of data, checking with DataType, 148, 
389 

typewriter input and output, 557 


unassing variables, 46 
unconditionally leaving your program, 47 
underflow, arithmetic, 525 
UNGUARDED option of :: ATTRIBUTE, 83 
UNGUARDED option of :: METHOD, 87, 543 
UNGUARDED subkeyword 

in a METHOD directive, 85 

in an ATTRIBUTE directive, 81 
uninherit method 

of Class class, 130 
uninit method 

of Stream class, 206 
uninitialized variable, 28 
union method 

of Bag class, 231 

of Collection class, 212 

of OrderedCollection class, 215 

of Relation class, 266 

of Set class, 270 
unknown method 

of Directory class, 242 

of Monitor class, 328 

of Stem class, 276 
unpacking a string 

with b2x, 137, 378 

with c2x, 140, 381 
UNPROTECTED subkey word 

in a METHOD directive, 85 

in an ATTRIBUTE directive, 81 
unsetMethod method 

of Directory class, 243 

of Object class, 122 
UNTIL phrase of DO instruction, 45 
UNTIL phrase of LOOP instruction, 57 
UNTIL subkeyword 

in a DO instruction, 45, 586 

ina LOOP instruction, 56, 586 
unusual change in flow of control, 527 
UPPER function 
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description, 425 
upper method 

of MutableBuffer class, 337 

of String class, 162 
UPPER subkeyword 

in a PARSE instruction, 41, 59, 510 

in an PARSE instruction, 64 
uppercase translation 

during ARG instruction, 41 

during PULL instruction, 64 

of symbols, 14 

with PARSE UPPER, 60 

with TRANSLATE function, 424 

with translate method, 160, 337 
Usa option of DATE function, 392 
usaDate method 

of DateTime class, 303 
USE instruction 

description, 78 

example, 79 
user input and output, 557, 567 
USER subkey word 

in a CALL instruction, 42, 529, 533 

in a RAISE instruction, 66 

in a SIGNAL instruction, 72, 529, 533 
USERID function 

description, 426 
utcDate method 

of DateTime class, 303 
utcIsoDate method 

of DateTime class, 300 


value, 18 
VALUE function 
description, 426 
example, 426, 428 
value method 
of WeakReference class, 358 
VALUE option of PARSE instruction, 61 
VALUE subkeyword 
in a NUMERIC instruction, 58 
in a PARSE instruction, 59, 511 
in a SIGNAL instruction, 72 
in a TRACE instruction, 73 
in an ADDRESS instruction, 39 
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VAR function 
description, 428 
example, 428 
VAR option of PARSE instruction, 61 
VAR subkeyword 
in a PARSE instruction, 59, 511 
variable 
access with VALUE function, 426 
checking name, 428 
compound, 32 
controlling loops, 584 
description, 28, 28 
dropping of, 46 
exposing to caller, 62 
external collections, 426 
global, 426 
in internal functions, 62 
in subroutines, 62 
names, 14 
new level of, 62 
parsing of, 61 
patterns, parsing with 
string, 509 
patterns, parsing with positional, 510 
positional patterns, 510 
reference, 509 
resetting of, 46 
setting a new value, 28, 28 
SIGL, 533 
simple, 29 
special 
RC, 36 
SIGL, 44, 533 
string patterns, 509 
testing for initialization, 420 
valid names, 28 
variable initialization, 420 
variables 
aquiring, 6, 9 
in objects, 4 
variables method 
of RexxContextclass, 357 
VERIFY function 
description, 429 
example, 429 
verify method 
of MutableBuffer class, 338 
of String class, 162 


verifying contents of a buffer, 338 
verifying contents of a string, 162, 429 
VERSION option of PARSE instruction, 62 
VERSION subkeyword 

in a PARSE instruction, 59, 511 


WeakReference class, 357 
weekDay method 
of DateTime class, 301 
Weekday option of DATE function, 392 
WHEN 
as free standing clause, 39 
WHEN subkeyword 
in a SELECT instruction, 70 
in an GUARD instruction, 51 
WHILE phrase of DO instruction, 45 
WHILE phrase of LOOP instruction, 57 
WHILE subkeyword 
in a DO instruction, 45, 586 
in a LOOP instruction, 56, 586 
whitespace, 10 
adjacent to special character, 9 
in parsing, treatment of, 502 
removal with STRIP function, 418 
removal with strip method, 159 
whole numbers 
checking with dataType, 148, 389 
description, 15 
Windows OS Error Codes, 435 
WITH subkeyword 
in a PARSE instruction, 59 
word 
alphabetical character options in TRACE, 
74 
counting in a mutable buffer, 339 
counting in a string, 164, 431 
deleting from a mutablebuffer, 333 
deleting from a string, 150, 394 
extracting from a mutable buffer, 339 
extracting from a string, 160, 164, 337, 
419, 431 
finding length of, 154, 400 
in parsing, 501 
locating in a mutable buffer, 339 
locating in a string, 144, 163, 332, 430 
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parsing 
conceptual view, 517 
examples, 501 
WORD function 
description, 429 
example, 429 
word method 
of MutableBuffer class, 339 
of String class, 163 
WORDINDEX function 
description, 430 
example, 430 
wordIndex method 
of MutableBuffer class, 339 
of String class, 163 
WORDLENGTH function 
description, 430 
example, 430 
wordLength method 
of MutableBuffer class, 339 
of String class, 163 
WORDPOS function 
description, 430 
example, 430 
wordPos method 
of MutableBuffer class, 339 
of String class, 163 
WORDS function 
description, 431 
example, 431 
words method 
of MutableBuffer class, 339 
of String class, 164 
writ position in a stream, 558 
writing to external data queue 
with PUSH, 65 
with QUEUE, 65 


X2B function 
description, 431 
example, 431 

x2b method 
of String class, 164 

X2C function 
description, 431 
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example, 432 
x2c method 
of String class, 165 
X2D function 
description, 432 
example, 432, 432 
x2d method 
of String class, 165 
xor method 
of Bag class, 231 
of Collection class, 212 
of Directory class, 243 
of OrderedCollection class, 215 
of Relation class, 267 
of Set class, 270 
XOR, logical, ?? 
XORing character strings together, 139, 380 
XRANGE function 
description, 432 
example, 433 


year method 

of DateTime class, 297 
yearDay method 

of DateTime class, 301 
YO subkeyword 

in a FORWARD instruction, 49 


тегов 
added on left with RIGHT function, 407 
added on left with right method, 158 
removal with STRIP function, 418 


removal with strip method, 159 
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